sales-skills/sales-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×).