Pipedrive API Integration Guide

Pipedrive’s API has a narrower surface than Salesforce’s or HubSpot’s, but two decisions still trip up most first-time integrations: which authentication method actually fits the job, and how the 2026 token-based rate-limit system changes what “budget” even means. This guide covers both, plus webhook verification (which works differently than most CRMs), the custom-field hash-key pattern that breaks integrations silently, the v1-to-v2 migration deadline that’s already passed, and the Marketplace app model for anything you’ll distribute beyond one account. If you’re deciding whether to build this in-house or bring in help, Pipedrive’s implementation cost guide breaks down what agencies typically charge for setup and integration work against a straightforward per-seat license quote.

Should you use an API token or OAuth 2.0?

The right starting question isn’t “which is easier to set up” — it’s “whose account does this run against, and who else needs to install it.” A personal API token is a static string, generated in Settings under Personal Preferences, tied to exactly one Pipedrive user. It’s passed either as a query parameter (?api_token=YOUR_TOKEN) or in the x-api-token header, and it inherits that user’s full data access. There’s no consent screen and no refresh cycle to manage, which makes it the fastest path for a script or internal tool running against a single company’s account.

OAuth 2.0 is the documented path for anything meant to run in production or be installed by more than one company. Pipedrive’s own authentication documentation frames OAuth as the preferred method for production integrations, largely because a personal token attributes every action to one specific user in Pipedrive’s audit logs — not to “the integration” as a distinct actor — and stops working outright if that user’s account is deactivated or the token is manually regenerated. An OAuth app, by contrast, authenticates as itself, survives individual user churn, and is the only method that can be listed on the Pipedrive Marketplace for other companies to install.

If you’re writing a one-off migration script or a reporting pull that only your team will ever run, a personal API token is a reasonable, low-friction choice. If you’re building something that needs to survive staff turnover, run unattended for months, or eventually be installed by a client’s own Pipedrive account rather than yours, start with OAuth from day one — retrofitting OAuth onto an integration built around a hardcoded personal token is more rework than starting there.

How the OAuth 2.0 flow actually works

Pipedrive’s OAuth implementation follows the standard Authorization Code grant. A user is sent to https://oauth.pipedrive.com/oauth/authorize with your app’s client_id, a registered redirect_uri, and an optional state parameter for CSRF protection. After the user approves access, Pipedrive redirects back with an authorization code — and per Pipedrive’s OAuth authorization documentation, that code expires in 5 minutes, so the exchange needs to happen immediately, not queued for later processing.

POST https://oauth.pipedrive.com/oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=YOUR_REDIRECT_URI

The resulting access_token expires after 60 minutes — noticeably shorter than the roughly hour-long window some other CRM platforms use, but similar in practice, meaning refresh handling isn’t optional for anything running unattended for more than an hour. The refresh_token that comes back in the same response stays valid as long as it’s used at least once every 60 days; go two months without refreshing it and the user has to reinstall the app and re-authorize from scratch. That refresh-token expiry window is worth building a monitoring alert around directly, since a dormant integration (a client who paused usage, a scheduled job that silently stopped running) can drift past 60 days without anyone noticing until the reinstall prompt shows up.

One detail worth flagging for storage: Pipedrive’s own documentation recommends a minimum varchar(768) column for token storage, because token length varies and a truncated token fails silently rather than erroring clearly at write time. It’s a small thing, but it’s the kind of detail that only surfaces once, in production, on whichever token happens to run long that week.

What changed with Token-Based Rate Limits

Pipedrive moved to a Token-Based Rate Limit (TBRL) system in 2026, replacing the older flat request-count limits. Per Pipedrive’s rate limiting documentation and the official TBRL announcement, each company gets a daily token budget calculated as 30,000 base tokens per seat, multiplied by a plan-tier factor: 1x on Lite, 2x on Growth, 5x on Premium, and 7x on Ultimate. Companies on Growth and above can also purchase top-ups in blocks of 250,000 tokens, up to ten blocks, if the base budget runs short.

The shift that actually changes integration design is that every endpoint costs a different number of tokens rather than counting as one flat request. A single-entity retrieval (pulling one deal by ID) costs roughly 2 tokens. A list-of-entities call costs around 20. An update costs about 10, a deletion about 6, and a search operation — the most expensive common operation — costs around 40. Two integrations making the same number of API calls can draw down wildly different amounts of budget depending on which endpoints they favor.

That spread matters most for exactly the kind of job that catches teams off guard: a one-time historical sync. Consider a 5-seat team on Lite, running the full 150,000-token daily budget. A backfill enriching 10,000 person records — pulling each person (about 2 tokens), their linked organization (about 2 tokens), and a search for related open deals (about 40 tokens, since search is the expensive operation) — comes out to roughly 44 tokens per person, or about 440,000 tokens for the full run. That’s nearly three times a Lite team’s entire daily budget, consumed by one backfill before any of that day’s normal sync traffic even starts.

Two adjustments fix that math. First, replace the per-person search call with a list-of-deals call filtered by organization where possible — list calls cost around 20 tokens regardless of how many records they return, so batching flips the economics entirely. Second, schedule large backfills to run across multiple days against the 30,000-token-per-seat daily budget rather than assuming one continuous run, and track the x-ratelimit-remaining and x-daily-requests-left response headers live rather than estimating from a fixed number, since normal sync and webhook-driven traffic draws from the same shared pool throughout the day. Migrating list-heavy calls to v2 endpoints also helps directly — Pipedrive’s own documentation notes that v2 endpoints carry lower token costs than their v1 equivalents for the same operation, which is one more reason the v1-to-v2 migration isn’t purely about avoiding deprecation.

There’s also a burst-level limit layered on top of the daily token budget, separate from it and worth watching independently. The x-ratelimit-limit and x-ratelimit-remaining headers report a short rolling window — documented at 2 seconds — so a script firing requests in a tight loop can trip a 429 well before it’s anywhere near exhausting its daily token allowance. That’s a different failure mode than running out of daily budget, and it needs a different fix: a small delay or a concurrency cap between calls, not a bigger daily allotment. Treat the two limits as independent constraints when writing retry logic — a 429 caused by burst throttling should back off for a second or two and retry, while a 429 caused by daily budget exhaustion should stop entirely until the next reset, since retrying immediately in that second case just adds failed calls to a budget that’s already at zero.

Why the v1-to-v2 migration is already overdue, not optional

If you’re evaluating a new Pipedrive integration today, this section should be short: build on v2. Selected Pipedrive API v1 endpoints — covering Deals, Persons, Organizations, Activities, Products, Pipelines, Stages, Search, and Fields, per Pipedrive’s v2 migration guide — were deprecated ahead of their v2 replacements, and the sunset date for those deprecated endpoints was July 31, 2026. As of this writing, that date is already behind us. Any integration still calling a deprecated v1 endpoint isn’t running on borrowed time anymore; it’s actively receiving 410 Gone responses right now.

Practically, that means the audit step isn’t optional either: check which endpoints a legacy integration actually calls, confirm whether each has a v2 equivalent (all nine core resource groups above do), and rebuild the request shape around cursor-based pagination rather than the old offset-based start/limit parameters. Cursor pagination doesn’t degrade the way offset pagination does on large collections, since it doesn’t have to skip past every prior record on each page — that’s a real performance gain on top of being the only option v2 supports. If an endpoint you rely on wasn’t in that list of nine, check the v2 migration guide directly rather than assuming; Pipedrive’s own migration notes are the more current reference than most third-party tutorials still describing the old request-count rate limits.

Custom fields, webhooks, and the details third-party tutorials skip

Custom fields are one of the more common sources of a “why did this break overnight” bug report. Pipedrive doesn’t expose custom fields by their display name in the API — each one is addressed by a key, a dynamically generated 40-character hash created the moment the field is added. That key doesn’t change if someone edits the field’s label in the UI, but it does change if the field gets deleted and recreated, or duplicated as a new field with a similar name. An integration that hardcoded a field’s hash key during setup, rather than pulling it fresh from the Fields API, will silently stop writing to the right field the next time someone in sales ops “fixes” a custom field by recreating it.

Webhooks are the other area where Pipedrive genuinely differs from most comparable CRMs, and it’s worth being direct about it rather than assuming standard practice carries over. Pipedrive doesn’t sign webhook payloads with HMAC or anything resembling a Standard Webhooks-compliant signature. Security is handled through HTTP Basic Auth: when you create a webhook — via the API or through Settings > Tools and apps > Webhooks in the UI — you set an http_auth_user and http_auth_password, and Pipedrive includes those credentials in the standard Authorization: Basic header on every delivery. Verifying a webhook, in practice, means checking that incoming Basic Auth credentials match what you configured, not computing and comparing a signature the way you would with most other platforms’ webhook systems. Copying signature-verification code written for a different CRM onto a Pipedrive integration won’t just fail — it’s checking for something that doesn’t exist here.

A webhook subscription is identified by an event_action and event_object pair joined with a dot — create.deal, change.person, delete.organization — and both positions accept a * wildcard, so *.deal catches every deal event and create.* catches every creation event across resource types. Delivery expectations are worth building retry logic around explicitly: Pipedrive treats any 2XX response as success, times requests out at 10 seconds, and retries a failed delivery three times at 3, 30, and 150 seconds after the first attempt. An endpoint that racks up ten first-attempt failures gets banned for 30 minutes, and a subscription with zero successful deliveries for three consecutive days is deleted outright — so a staging endpoint left pointed at a webhook in production, or a deploy that briefly takes the receiving endpoint down, can quietly lose the subscription entirely if it’s down long enough.

How should a webhook receiver handle duplicates and retries?

Build the receiver so processing the same event twice is harmless, because with retries at 3, 30, and 150 seconds, a slow response can produce a second delivery of an event you already handled. The pattern has four parts, and none of them depend on a signature Pipedrive doesn’t send.

Authenticate first, cheaply. Compare the incoming Basic Auth header to the credentials you configured before parsing the body, and return 401 on a mismatch. Use a constant-time comparison rather than a plain string equality check, and serve the endpoint over HTTPS only, since Basic Auth credentials are effectively plaintext without it.

Acknowledge fast, process later. Pipedrive times a delivery out at 10 seconds, so return a 2XX as soon as the payload is validated and queued, and do the actual CRM-side work (API lookups, writes to your database, downstream calls) in a background job. A receiver that does a search call inline and takes 12 seconds under load will trigger retries of events it did successfully process, and repeated failures move the endpoint toward the 30-minute ban described above.

Read the payload by action, not by assumption. In the v2 webhook payload, the meta object carries the action, entity, and entity ID, data holds the current state, and previous behaves differently by action: it’s null on create, holds only the changed fields on a change, and holds the last known state on delete. Code that reads previous on a create event without a null check is one of the more common causes of a receiver that works in testing and throws on the first real deal creation.

Deduplicate before acting. Store a key for each processed event, built from the entity type, entity ID, action, and the record’s update timestamp if the payload includes one, and skip anything already seen. If your downstream action isn’t naturally idempotent (creating a task, sending a message), the dedupe check is the only thing between a retry and a customer receiving two emails.

A minimal receiver skeleton, in pseudocode:

on POST /pipedrive-webhook:
    if not basic_auth_matches(request.headers): return 401
    event = parse(request.body)
    key = event.meta.entity + ":" + event.meta.entity_id + ":" + event.meta.action + ":" + event.data.update_time
    if seen(key): return 200
    enqueue(event); mark_seen(key)
    return 200

Treat the exact fields available for the dedupe key as something to confirm against a real payload from your own account, since which timestamp fields appear varies by entity type.

Bulk updates deserve a specific mention. One user changing five hundred deals in the Pipedrive interface can produce a burst of webhook deliveries, and if your handler writes back to Pipedrive in response to each one, you can hit the burst rate limit and get 429 responses on your own writes. The Pipedrive developer community has documented this pattern, and the usual mitigation is to queue writes with a small concurrency cap rather than firing one API call per incoming event. It also pays to make sure your own writes don’t re-trigger the webhook that caused them: an update handler that changes a field, which fires a change webhook, which triggers the same handler, is a loop that will spend a daily token budget in minutes.

What do the common API errors mean in practice?

Most failures fall into a short list, and each one has a different correct response:

• 401 Unauthorized. With a personal token, it means the token was regenerated or the user was deactivated. With OAuth, it usually means the 60-minute access token expired, so refresh it once and retry the request. If the refresh itself fails, the refresh token has lapsed (the 60-day window) or the user uninstalled the app, and the only fix is re-authorization.
• 403 Forbidden. The authenticated user lacks permission for that object or the app’s granted scopes don’t cover the endpoint. Adding scopes to an OAuth app requires users to re-approve the installation.
• 404 Not Found. Often a deleted record or a stale ID cached in your own database. Reconcile rather than retry.
• 410 Gone. For a deprecated v1 endpoint, this is the sunset behavior described earlier. Retrying will never succeed; the request needs to move to v2.
• 429 Too Many Requests. Distinguish burst throttling from daily-budget exhaustion by inspecting the rate-limit headers before deciding whether to back off for seconds or stop until reset.
• 5xx. Retry with exponential backoff and jitter, capped at a small number of attempts, and log the request ID so a failed call can be traced later.

Logging deserves one more line. Record the endpoint, status code, and the remaining-token header on every non-2XX response. When an integration starts failing intermittently at 3pm every afternoon, a week of that log tells you in minutes whether it’s a rate-limit pattern, an expiring token, or something on your own side.

The Marketplace app model: private versus public

Pipedrive’s Developer Hub — the current name for what used to be called Marketplace Manager — is where OAuth apps get registered, regardless of whether they’re ever meant to be publicly discoverable. The choice between a private and a public app has to be made at creation and can’t be changed later, so it’s worth getting right up front.

A private app skips Pipedrive’s review process entirely and never gets a public Marketplace listing; it’s shared with specific companies through a direct, unlisted install link. That’s the right shape for most agency work — building an integration for your own company’s account, or for a defined set of client accounts, without needing anyone outside those companies to ever find or install it. A public app has to go through Pipedrive’s Developer Partner approval process before it can be published, and even after approval it doesn’t go live automatically — the app sits in an “Unpublished” state until the developer manually publishes it. Public apps make sense specifically when the goal is a distributable product any Pipedrive user can discover and install on their own, not just a client-facing integration built for a defined set of accounts.

When the direct API earns its complexity over Zapier or Make

None of this — OAuth flows, token budgeting, custom field hash keys, webhook Basic Auth — is required to get real value out of a Pipedrive integration in every case. For lighter, lower-volume connections between Pipedrive and the rest of a business’s stack, a no-code automation platform is often the faster and more maintainable path, especially when the person maintaining the connection a year from now isn’t a developer. Teams in that position are usually better served by autoesta’s Zapier and Make automation team, which builds those Pipedrive connections visually without writing or maintaining custom API code.

Direct API integration earns its added complexity at higher sustained request volume, when a no-code connector’s field mapping can’t express the custom-object or hash-key logic you need, or when you’re building something meant to be installed across multiple client accounts rather than wired permanently into one. It’s also the better fit for real-time, webhook-driven workflows rather than anything running on a polling schedule. There’s no single published breakeven point between the two approaches in cost or volume terms — that’s a decision worth making based on the shape of your specific integration, not a generic rule of thumb someone else’s blog post claims to have found.

The other variable worth naming honestly is who owns the result after launch. A Zapier or Make scenario lives in a visual canvas that an operations person can usually read and adjust without pulling in a developer. A direct API integration is code — versioned, tested, and deployed the way any other application in your stack is, which typically means it needs a developer or an implementation partner involved for anything beyond the initial build. If the actual requirement is “automate what happens after a deal moves stage,” rather than “build a piece of custom software,” it’s also worth checking whether the automation belongs inside Pipedrive’s own workflow tools first, since not every integration project needs a custom API layer at all — plenty of what looks like an integration requirement turns out to be solvable with native automation once it’s scoped properly, the same way HighLevel Automation Team approaches that scoping question on the GoHighLevel side before recommending custom development.

Getting started without the common mistakes

Most Pipedrive integration problems trace back to a small set of avoidable decisions made early: picking a personal API token for something that needed to survive staff turnover, disabling or ignoring refresh-token handling until the 60-day window lapses, budgeting a backfill against request count instead of token cost, hardcoding a custom field’s hash key instead of pulling it fresh, or assuming webhook payloads are signed the way they are on other platforms. None of these require deep platform expertise to avoid — they require deciding on the auth model, the rate-limit strategy, and the webhook verification approach before the first request gets written, rather than after debugging a broken integration that’s already in production.

For teams weighing whether to build custom API integration in-house versus using Pipedrive’s own automation features first, that scoping conversation is worth having explicitly before committing engineering time, since Pipedrive’s native workflow automation covers a meaningful share of what teams initially assume needs a custom integration. And if you’re setting up Pipedrive from scratch rather than integrating into an existing account, how to set up Pipedrive covers the platform-side configuration this guide assumes is already in place.

If you’re scoping a Pipedrive integration and want a second read on the auth model or rate-limit budget before you build, aibrevo’s Pipedrive implementation team works with this API day to day and can sanity-check an approach — token strategy, webhook design, custom-field mapping — before it turns into a rebuild six months in.