What we do
Tools
Industries
Department
How we workLet's talk →
Home/Pipedrive/Pipedrive API
Pipedrive developer notes

Pipedrive API Reference: Auth, Token Budget, Webhooks v2 and the v1 Changes

Pipedrive's REST API reaches the same deals, persons, organizations, products and activities you see in the app, custom fields included. Calls go to your company's own domain, for example https://yourcompany.pipedrive.com/api/v2/deals. Before the first request, decide how you'll authenticate. Choosing what to link in the first place, before any code, is covered on the Pipedrive hub page.

Personal API token or OAuth app?

API token

Internal scripts for one company

  • Send it in the x-api-token header on every request.
  • Find it under your account name, then Company settings, Personal preferences, API. Each company you belong to has its own.
  • It acts as that user and sees what they see. You can only have one active token, so regenerating it breaks every script using the old one.
  • If API doesn't show in settings, an admin has turned off API access for users.
OAuth 2.0

Apps other companies install, or anything acting for many users

  • Register the app first, then run the authorization flow. Tokens come from https://oauth.pipedrive.com/oauth/token.
  • Access tokens expire after 60 minutes. Refresh them in the background.
  • A refresh token dies if it isn't used for 60 days, and the user has to reinstall the app.
  • OAuth apps get a larger burst allowance than API tokens on every plan.

A sync that only your company runs can live on an API token held by a service user, so it doesn't die when a rep leaves. Anything other accounts install needs OAuth.

How the daily token budget is spent

Pipedrive meters calls in tokens, not requests. Each company gets 30,000 base tokens a day, multiplied by a plan factor (Lite 1, Growth 2, Premium 5, Ultimate 7) and by the number of seats. Costs per call: 2 to get one record, 20 for a list, 10 to update, 6 to delete one, 40 to search. v2 endpoints generally cost less than v1.

Example: Growth plan, 8 seats, one sync running
Daily budget (30,000 × 2 × 8) 480,000
Polling the deal list every minute, 1,440 times (List call at 20 tokens) − 28,800
Fetching 3,000 changed deals one by one (2 tokens each) − 6,000
Writing 2,500 updates back (10 tokens each) − 25,000
Searching for a person before each of 4,000 inbound leads (40 tokens each: the expensive habit) − 160,000
Left for everyone else using the API today 260,200

The budget is shared by every integration on the company account, and it resets at midnight in the server's timezone, which may not be yours. Run out and calls return 429 until the reset. Separately, a burst limit applies per token over a rolling 2-second window, and search is held to 10 requests per 2 seconds on every plan. Watch the x-ratelimit-remaining and x-ratelimit-reset headers. An API-token client that keeps hammering after 429s can start getting 403 pages instead.

Webhooks v2, from subscription to a handler that holds up

Webhooks replace most polling, and outgoing webhooks don't count against the token budget.

  1. 1

    Subscribe to the narrowest trigger

    Settings Tools and apps Webhooks

    Or call POST /v1/webhooks with subscription_url, event_action and event_object. Version 2.0 is the default. Actions are create, change, delete or *; objects include deal, person, organization, product, activity, lead and more. change.deal is far quieter than *.*.

    Watch for: the limit of 40 webhooks per user. The URL must be public, can't redirect, and can't be a Pipedrive API endpoint.

  2. 2

    Protect the endpoint

    Set http_auth_user and http_auth_password when you create the webhook, and reject any request without them.

  3. 3

    Answer inside 10 seconds, then do the work

    Anything other than a 2XX, or no answer within 10 seconds, counts as a failure. Store the payload, return 200, and process it from a queue.

    Watch for: the ban rule. Ten failed first attempts and the webhook is switched off for 30 minutes, and events in that window are lost. After three days with no successful delivery, Pipedrive deletes the webhook.

  4. 4

    Expect retries and repeats

    A failed delivery is tried three more times, after 3, 30 and 150 seconds, and meta.attempt runs from 1 to 4. Key your processing on the object ID and its update time so a repeat does nothing.

  5. 5

    Read what changed, and who changed it

    data holds the record as it is now, and on a change event previous holds only the fields that moved. meta.change_source says whether the edit came from the app or the API, which is how you stop your own writes from firing your sync again.

v1 habits that break on v2

Pipedrive is moving endpoints to v2 a group at a time, with at least a year's grace before each v1 equivalent goes. Deals, persons, organizations, products, activities, pipelines, stages, fields and search are already there.

Custom fields at the top level

How you'll know: Your code reads a 40-character field key off the root of the deal and gets nothing.

Fix: In v2 they sit inside a custom_fields object. Money fields come back as value plus currency instead of a separate _currency key, and option IDs are numbers, in an array for multi-select fields.

Updating with PUT

How you'll know: Update calls that worked on v1 fail against /api/v2/.

Fix: v2 updates use PATCH. Only send the fields you mean to change.

Expecting the related records in the response

How you'll know: The deal arrives without the person's name or the owner's details.

Fix: v2 returns IDs, not embedded objects, and user_id is now owner_id. Fetch related records separately, or cache people and users on your side.

Paging with start

How you'll know: Lists stop at the first page.

Fix: v2 list endpoints page with cursor and limit (100 by default, 500 at most). Keep reading until additional_data.next_cursor comes back null.

Loose booleans and dates

How you'll know: Filters on 0 and 1 stop matching, and date parsing fails.

Fix: v2 only accepts true and false, and every timestamp is RFC 3339.

Where the API ends and the integration starts

The API gives you reads and writes. It doesn't decide which stage change should raise an invoice, what to do when the accounting system rejects a line, or which of two persons with the same email is the real one. That logic, plus retries and a nightly check that both sides still agree, is the bulk of any Pipedrive integration.

That's the part n-frames writes and keeps running: deal-triggered handoffs to accounting and fulfilment, stock and balances read onto the deal, and reporting that joins Pipedrive with data from elsewhere. See Pipedrive automation, Pipedrive reporting and what already connects for the non-code routes.

Questions people ask

Do I need a developer to use the Pipedrive API?

Not to look around. With your API token and Postman you can read deals in minutes. You do need one for anything that runs unattended: a webhook handler, a scheduled sync, a write into another system. That code has to cope with retries, limits and bad data, and keep doing it for years.

Does Pipedrive have rate limits on API calls?

Two kinds. A daily token budget for the whole company, set by plan and seats, and a burst limit per token over a rolling 2-second window. Search has its own cap of 10 requests per 2 seconds. Hitting either returns 429. The ledger above shows how a typical sync spends the budget.

Can the Pipedrive API reach custom fields?

Yes, on deals, persons, organizations, products and activities. Each one has a generated key rather than its label, so look the keys up through the fields endpoints and store them. In v2, custom field values sit in their own custom_fields object.

Is there an official Pipedrive API documentation site?

Yes, developers.pipedrive.com has the endpoint reference for v1 and v2, plus guides on authentication, rate limits, webhooks and the v2 migration. We build against those docs rather than guessing at behavior.

Are there official Pipedrive API client libraries?

Pipedrive publishes two official clients, for Node.js and PHP. From Python or anything else, plain HTTPS requests with the x-api-token header or an OAuth bearer token work fine.

Should new code use API v1 or v2?

v2 wherever the endpoint exists. It costs fewer tokens per call and is stricter about input. Fall back to v1 only for objects that haven't moved yet, and expect to port those calls later.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.