---
name: sales-pipedrive
description: "Pipedrive (pipedrive.com) platform help — pipeline-first sales CRM with deals, leads, persons/organizations, activities, automation, and reporting. Mature REST API v1+v2 (base {company}.pipedrive.com/api/v2, x-api-token header or OAuth 2.0, cursor pagination, free webhooks; v1 is sunsetting) plus OpenAPI specs. Use when building a Pipedrive API or webhook integration, deciding between API v1 and v2 or migrating before the v1 shutdown, hitting the daily token rate limit (429), custom fields showing as random 40-character hash keys, webhooks duplicating/missing or auto-deleting after failures, syncing deals or persons into a warehouse or Slack, choosing OAuth vs API token, or picking a plan (Lite/Growth/Premium/Ultimate) and understanding the token-budget multiplier. Do NOT use for CRM selection/comparison across tools (use /sales-crm-selection), CRM data cleanup/dedupe (use /sales-data-hygiene), or outbound sequence design (use /sales-cadence)."
argument-hint: "[describe what you need help with in Pipedrive]"
license: MIT
version: 1.0.1
tags: [sales, crm, platform]
github: "https://github.com/pipedrive"
---

# Pipedrive Platform Help

## Step 1 — Gather context

If `references/learnings.md` exists, read it first for accumulated platform knowledge.

1. **What are you trying to do?**
   - A) Build an API integration — create/update deals, persons, organizations, leads, activities
   - B) Set up webhooks to push CRM changes into a warehouse/CRM/Slack
   - C) Migrate from API v1 to v2 (before the 2026-07-31 v1 shutdown)
   - D) Fix a rate-limit / token-budget (429) problem
   - E) Work with custom fields (the 40-char hash keys)
   - F) Pick/understand a plan — Lite vs Growth vs Premium vs Ultimate, token multipliers, add-ons

2. **Auth model?** Single internal account/script → **API token** (`x-api-token`). Distributable Marketplace app installed by other accounts → **OAuth 2.0**.

3. **Which API version?** Default to **v2** (cursor pagination, cheaper tokens). Use **v1 only** for resources not yet on v2 (Leads, Notes, Webhooks, Files, Filters, Goals, Projects).

Skip-ahead rule: if the user's prompt already provides enough context, skip to Step 2.

## Step 2 — Route or answer directly

| If the question is about... | Route to... |
|---|---|
| CRM selection/comparison or migration strategy across tools | `/sales-crm-selection {question}` |
| CRM data cleanup, dedupe, record matching | `/sales-data-hygiene {question}` |
| Contact enrichment for CRM records | `/sales-enrich {question}` |
| Outbound sequence / cadence design across platforms | `/sales-cadence {question}` |
| Lead scoring model design | `/sales-lead-score {question}` |
| Revenue forecasting methodology | `/sales-forecast {question}` |
| Connecting Pipedrive to other tools generically (iPaaS) | `/sales-integration {question}` |

When routing, give the exact command, e.g. "This is a CRM-comparison question — run: `/sales-crm-selection should I move from Pipedrive to HubSpot at 25 people`".

## Step 3 — Pipedrive platform reference

**Read `references/platform-guide.md`** for the full reference — the module map (what's API v2 vs v1-only vs UI-only), the pricing model (API is on **every** plan; only the **token budget** scales by multiplier), the data model with JSON shapes, and quick-start recipes (create a deal from a form; listen for deal-won via webhook; nightly incremental export).

**Read `references/pipedrive-api-reference.md`** for the integration surface — base URLs, `x-api-token` vs OAuth auth, the `{success, data, additional_data}` envelope, v2 cursor pagination, the resource list (and which are v1-only), the webhook payload/retry rules, the token-based rate-limit formula, and the **custom-field hash-key** mechanics.

Answer using only the relevant section. Don't dump the full reference.

## Step 4 — Actionable guidance

Focus on the user's specific situation:

- **Default to v2; the clock is real.** v1 fully shuts down **2026-07-31**. v2 uses the `x-api-token`
  header, **cursor** pagination (`limit`+`cursor`), and `PATCH` for updates, and costs ~half the tokens.
  Keep v1 only for Leads/Notes/Webhooks/Files/Filters/Goals/Projects.
- **Custom fields are 40-char hashes, not names.** Pull the hash→label map from `GET /api/v1/dealFields`
  (or `personFields`/`organizationFields`) and cache it; never hard-code a label. Hashes differ per account.
- **Budget tokens, don't just retry.** Daily budget = `30,000 × plan-multiplier × seats`. On `429` you're
  out for the day unless you top up — so migrate to v2, prefer **free webhooks** over polling, and use
  `updated_since` for incremental pulls.
- **Make webhook receivers bulletproof.** ACK `200` immediately and process async; retries are 3/30/150s,
  10 first-attempt fails → 30-min ban, and **3 days with no success auto-deletes the webhook**. Dedupe on
  object id + `meta.timestamp`.
- **Pick auth by distribution.** API token for your own account; OAuth 2.0 for a Marketplace app (use the
  returned `api_domain` as the base URL).
- **Plan choice is about token budget + features, not API access.** Every plan has the API; higher tiers
  add email sync/automation/forecasting and a bigger token multiplier. Watch the paid add-ons.

If you discover a gotcha, workaround, or tip not covered in `references/learnings.md`, append it there.

## Gotchas

> *Best-effort from research (2026-06) — review these, especially pricing and the v1 shutdown date, which change.*

1. **API v1 shuts down 2026-07-31.** New integrations must target v2; existing v1 code needs migration. Don't build new work on v1.
2. **Custom fields are random 40-char hash keys.** A field labeled "Tier" is referenced as e.g. `dcf558aac1ae4e8c4f849ba5e668430d8df9be12` — map via the `*Fields` endpoints.
3. **Token-based daily rate limit, not per-second.** Hit the daily budget and you get `429` until reset. v2 is ~50% cheaper than v1; webhooks are free.
4. **Webhooks auto-delete after 3 days of failures** (and ban for 30 min after 10 first-attempt fails). A downstream outage can silently kill your integration.
5. **Leads ≠ Deals, and Leads are v1-only.** The Leads inbox is a pre-deal stage with its own v1 API; don't expect a v2 `/leads` endpoint yet.
6. **v2 uses `PATCH` (v1 used `PUT`) and cursor pagination** (`additional_data.next_cursor`), not v1's `start`/`limit` offset. Porting code requires both changes.
7. **Costly add-ons.** LeadBooster, Web Visitors, Campaigns, Smart Docs, and Projects are paid extras on top of seats — total cost can exceed the headline per-seat price.
8. **Base URL is company-specific.** Calls go to `https://{your-company}.pipedrive.com/api/...`; for OAuth apps use the `api_domain` returned at token exchange, not a hard-coded domain.

## Related skills

- `/sales-crm-selection` — CRM comparison, selection, and migration strategy across tools (is Pipedrive the right CRM, or time to switch?)
- `/sales-data-hygiene` — CRM data quality: dedupe, record matching, enrichment automation
- `/sales-enrich` — Contact enrichment (emails, phones, company data) for Pipedrive records
- `/sales-cadence` — Outbound sequence/cadence design across platforms (Pipedrive isn't a sequencer)
- `/sales-integration` — Connecting Pipedrive to other tools via webhooks/Zapier/Make
- `/sales-do` — Not sure which skill to use? The router matches any sales objective to the right skill. Install: `npx skills add sales-skills/sales --skill sales-do -a claude-code`

## Examples

### Example 1: Create a deal when a form is submitted (developer/automation)
**User says**: "When someone fills out my pricing form, I want a deal created in Pipedrive in the right pipeline."
**Skill does**: Walks Recipe 1 — upsert the **person** (`POST /api/v2/persons`), then create the **deal** (`POST /api/v2/deals`) with `person_id`, `pipeline_id`, `stage_id`, authenticated with the `x-api-token` header. Notes to target **v2** (v1 dies 2026-07-31), and that setting a custom field requires its **40-char hash** from `GET /api/v1/dealFields`. Offers the no-code Zapier path as an alternative.
**Result**: Form submissions create properly-staged deals via the API.

### Example 2: My integration started returning 429
**User says**: "My nightly sync to BigQuery suddenly fails with 429 errors."
**Skill does**: Explains Pipedrive's **token-based daily budget** (`30,000 × plan-multiplier × seats`) — you've exhausted it, not a per-second cap. Fixes: migrate the sync to **v2** (~50% cheaper tokens), use `updated_since` cursor pulls instead of full scans, replace polling with **free webhooks** where possible, and buy a token top-up or raise the plan multiplier if still tight. Shows the backoff loop from the API reference.
**Result**: The sync fits within budget and stops 429-ing.

### Example 3: Should I stay on Pipedrive?
**User says**: "We're 30 people now and Pipedrive's reporting feels limiting — move to HubSpot?"
**Skill does**: Recognizes this as a cross-tool selection question and routes: "run: `/sales-crm-selection we're 30 people outgrowing Pipedrive's reporting, HubSpot vs alternatives`." Briefly notes Pipedrive's reporting limits and add-on costs are common switch triggers, but defers the comparison/migration plan to the strategy skill.
**Result**: User is handed to the right strategy skill with a ready prompt.

## Troubleshooting

### My API token works on some calls but a create/update fails
**Symptom**: GETs succeed but POST/PATCH returns errors, or a custom field won't set.
**Cause**: Using the field's display name instead of its **40-char hash key**, sending to v1 with v2 syntax (or vice-versa), or using `PUT` on v2 (v2 wants `PATCH`).
**Solution**: Fetch the field map from `GET /api/v1/dealFields` and use the `key` hash. Confirm the version: v2 base `/api/v2`, `x-api-token` header, `PATCH` for updates; v1 base `/api/v1`, `?api_token=`. Match the request body to the OpenAPI spec for that version.

### My webhook stopped firing
**Symptom**: Events arrive for a while, then nothing.
**Cause**: Pipedrive bans a webhook for 30 minutes after 10 first-attempt failures and **auto-deletes** it after 3 consecutive days with no successful (2xx) delivery — usually a downstream outage or slow (>10s) endpoint.
**Solution**: Make the receiver ACK `200` instantly and process async; verify HTTP Basic Auth matches; check it's reachable over public HTTPS. Recreate the webhook (`POST /api/v1/webhooks`) and add monitoring/alerting so a future outage doesn't silently delete it. Remember webhooks are free — they don't consume tokens.

### Hitting the daily rate limit
**Symptom**: `429 Too Many Requests`, often later in the day.
**Cause**: The **daily token budget** is exhausted (`30,000 × plan-multiplier × seats`), not a per-second throttle.
**Solution**: Migrate to **v2** (~half the token cost), switch full scans to `updated_since` incremental pulls, move polling to **webhooks**, cache reference data, and—if still constrained—buy API token top-ups or move to a higher plan multiplier (Lite 1× → Growth 2× → Premium 5× → Ultimate 7×).