A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Pipedrive API is how an app or AI agent works with a sales pipeline: creating a deal, looking up the person or organization behind it, logging an activity, or converting a lead. Access is granted through an OAuth access token or a personal API token, and an OAuth token carries scopes that decide which areas a call can read or change. Pipedrive runs a current generation of the API alongside an older one, and it can push a notification to a registered endpoint whenever a record changes.
How an app or AI agent connects to Pipedrive determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the token behind it and the scopes that token carries.
The REST API takes JSON request bodies and returns JSON, and a call goes to the company's own host (the api_domain returned at install, like {company}.pipedrive.com). Version 2 paths under /api/v2 use cursor pagination and PATCH updates; version 1 paths under /api/v1 serve the resources version 2 has not yet replaced. A request authenticates with an OAuth Bearer token or a personal API token.
Pipedrive POSTs a JSON payload to a registered URL when an event happens, named as an action and an object like added.deal or updated.person, with wildcards such as *.deal supported. Webhooks are created with POST /api/v1/webhooks and default to the v2 format. The receiving endpoint can require HTTP basic auth. A failed delivery is retried at 3, 30, and 150 seconds, and 10 failures pause the hook for 30 minutes.
An app a customer installs uses the OAuth 2.0 authorization-code flow. The customer approves a set of scopes, and the app exchanges the resulting code for a Bearer access token that lasts 60 minutes and a refresh token that lasts 60 days of inactivity. The token response also returns an api_domain, the company-specific host every later call must use.
A single account can call the API with a personal API token, a long-lived key tied to one user and found in that user's settings. It carries that user's own permissions rather than a requested set of scopes, so it can reach whatever the user can. It suits a single-company script or internal integration, not a distributed app.
The Pipedrive API is split into the parts of a sales pipeline an agent can act on, like deals, the people and companies behind them, activities, and leads. Each area has its own methods, and a write can move a deal, change a contact, or delete a record.
Methods for working with deals, the ongoing sales tied to a person or organization.
Methods for working with persons, the individual contacts behind deals.
Methods for working with organizations, the companies contacts and deals belong to.
Methods for working with activities, the calls, meetings, and tasks logged against records.
Methods for working with leads, the early inbox of potential deals before qualification.
Methods for working with notes attached to deals, persons, and organizations.
Methods for reading the pipelines and stages a deal moves through.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
DealsMethods for working with deals, the ongoing sales tied to a person or organization.6 | ||||||
| GET | /api/v2/deals | List deals, with cursor pagination and filters such as owner, stage, and status. | read | deals:read | Current | |
Read-only. A list call costs 20 tokens on the daily budget. Acts ondeal Permission (capability) deals:readVersionAvailable since the API’s base version Webhook eventNone Rate limit20 tokens SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/deals/:id | Retrieve a single deal by id. | read | deals:read | Current | |
Read-only. A single read costs 2 tokens. Acts ondeal Permission (capability) deals:readVersionAvailable since the API’s base version Webhook eventNone Rate limit2 tokens SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/deals | Create a deal, with a title, value, and a pipeline stage. | write | deals:full | Current | |
Needs the full deals scope; the read scope cannot create. Acts ondeal Permission (capability) deals:fullVersionAvailable since the API’s base version Webhook event added.dealRate limit10 tokens SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/deals/:id | Update a deal, for example moving it to another stage or marking it won or lost. | write | deals:full | Current | |
Version 2 uses PATCH, not PUT. An update costs 10 tokens. Acts ondeal Permission (capability) deals:fullVersionAvailable since the API’s base version Webhook event updated.dealRate limit10 tokens SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/deals/:id | Delete a deal. | write | deals:full | Current | |
Removes the deal. A delete costs 6 tokens. Acts ondeal Permission (capability) deals:fullVersionAvailable since the API’s base version Webhook event deleted.dealRate limit6 tokens SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/deals/search | Search deals by title, notes, and custom fields, returning ranked matches. | read | search:read | Current | |
Uses the narrower search:read scope. A search costs 40 tokens, and the Search API is capped at 10 requests per two seconds. Acts ondeal Permission (capability) search:readVersionAvailable since the API’s base version Webhook eventNone Rate limit40 tokens SourceOfficial documentation ↗ | ||||||
Persons (contacts)Methods for working with persons, the individual contacts behind deals.6 | ||||||
| GET | /api/v2/persons | List persons (contacts), with cursor pagination and filters. | read | contacts:read | Current | |
Read-only. A list call costs 20 tokens. Acts onperson Permission (capability) contacts:readVersionAvailable since the API’s base version Webhook eventNone Rate limit20 tokens SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/persons/:id | Retrieve a single person by id. | read | contacts:read | Current | |
Read-only. A single read costs 2 tokens. Acts onperson Permission (capability) contacts:readVersionAvailable since the API’s base version Webhook eventNone Rate limit2 tokens SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/persons | Create a person (contact), with name, email, phone, and an organization link. | write | contacts:full | Current | |
Needs the full contacts scope, which covers both persons and organizations. Acts onperson Permission (capability) contacts:fullVersionAvailable since the API’s base version Webhook event added.personRate limit10 tokens SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/persons/:id | Update a person's details. | write | contacts:full | Current | |
Version 2 uses PATCH. An update costs 10 tokens. Acts onperson Permission (capability) contacts:fullVersionAvailable since the API’s base version Webhook event updated.personRate limit10 tokens SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/persons/:id | Delete a person (contact). | write | contacts:full | Current | |
Removes the contact. A delete costs 6 tokens. Acts onperson Permission (capability) contacts:fullVersionAvailable since the API’s base version Webhook eventNone Rate limit6 tokens SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/persons/search | Search persons by name, email, phone, notes, and custom fields. | read | search:read | Current | |
Uses search:read. A search costs 40 tokens, capped at 10 requests per two seconds. Acts onperson Permission (capability) search:readVersionAvailable since the API’s base version Webhook eventNone Rate limit40 tokens SourceOfficial documentation ↗ | ||||||
Organizations (companies)Methods for working with organizations, the companies contacts and deals belong to.6 | ||||||
| GET | /api/v2/organizations | List organizations (companies), with cursor pagination and filters. | read | contacts:read | Current | |
Read-only. Organizations share the contacts scope with persons. A list costs 20 tokens. Acts onorganization Permission (capability) contacts:readVersionAvailable since the API’s base version Webhook eventNone Rate limit20 tokens SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/organizations/:id | Retrieve a single organization by id. | read | contacts:read | Current | |
Read-only. A single read costs 2 tokens. Acts onorganization Permission (capability) contacts:readVersionAvailable since the API’s base version Webhook eventNone Rate limit2 tokens SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/organizations | Create an organization (company). | write | contacts:full | Current | |
Needs the full contacts scope. Acts onorganization Permission (capability) contacts:fullVersionAvailable since the API’s base version Webhook event added.organizationRate limit10 tokens SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/organizations/:id | Update an organization's details. | write | contacts:full | Current | |
Version 2 uses PATCH. An update costs 10 tokens. Acts onorganization Permission (capability) contacts:fullVersionAvailable since the API’s base version Webhook event updated.organizationRate limit10 tokens SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/organizations/:id | Delete an organization (company). | write | contacts:full | Current | |
Removes the company record. A delete costs 6 tokens. Acts onorganization Permission (capability) contacts:fullVersionAvailable since the API’s base version Webhook eventNone Rate limit6 tokens SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/organizations/search | Search organizations by name, address, notes, and custom fields. | read | search:read | Current | |
Uses search:read. A search costs 40 tokens, capped at 10 requests per two seconds. Acts onorganization Permission (capability) search:readVersionAvailable since the API’s base version Webhook eventNone Rate limit40 tokens SourceOfficial documentation ↗ | ||||||
ActivitiesMethods for working with activities, the calls, meetings, and tasks logged against records.5 | ||||||
| GET | /api/v2/activities | List activities, the calls, meetings, and tasks logged against records. | read | activities:read | Current | |
Read-only. A list costs 20 tokens. Acts onactivity Permission (capability) activities:readVersionIntroduced 2024-12-19 Webhook eventNone Rate limit20 tokens SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/activities/:id | Retrieve a single activity by id. | read | activities:read | Current | |
Read-only. A single read costs 2 tokens. Acts onactivity Permission (capability) activities:readVersionIntroduced 2024-12-19 Webhook eventNone Rate limit2 tokens SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/activities | Create an activity, like a call, meeting, or task, linked to a deal, person, or organization. | write | activities:full | Current | |
Needs the full activities scope. Acts onactivity Permission (capability) activities:fullVersionIntroduced 2024-12-19 Webhook event added.activityRate limit10 tokens SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/activities/:id | Update an activity, for example marking it done. | write | activities:full | Current | |
Version 2 uses PATCH. An update costs 10 tokens. Acts onactivity Permission (capability) activities:fullVersionIntroduced 2024-12-19 Webhook event updated.activityRate limit10 tokens SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/activities/:id | Delete an activity. | write | activities:full | Current | |
Removes the activity. A delete costs 6 tokens. Acts onactivity Permission (capability) activities:fullVersionIntroduced 2024-12-19 Webhook eventNone Rate limit6 tokens SourceOfficial documentation ↗ | ||||||
LeadsMethods for working with leads, the early inbox of potential deals before qualification.7 | ||||||
| GET | /api/v1/leads | List non-archived leads, the early potential deals before qualification. | read | leads:read | Current | |
Read-only. Most lead endpoints remain on version 1. Acts onlead Permission (capability) leads:readVersionAvailable since the API’s base version Webhook eventNone Rate limit20 tokens SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/leads/:id | Retrieve a single lead by id. | read | leads:read | Current | |
Read-only. A single read costs 2 tokens. Acts onlead Permission (capability) leads:readVersionAvailable since the API’s base version Webhook eventNone Rate limit2 tokens SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/leads | Create a lead, optionally linked to a person and organization. | write | leads:full | Current | |
Needs the full leads scope. Acts onlead Permission (capability) leads:fullVersionAvailable since the API’s base version Webhook eventNone Rate limit10 tokens SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/leads/:id | Update a lead's properties. | write | leads:full | Current | |
Leads use PATCH on version 1. An update costs 10 tokens. Acts onlead Permission (capability) leads:fullVersionAvailable since the API’s base version Webhook eventNone Rate limit10 tokens SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/leads/:id | Delete a lead. | write | leads:full | Current | |
Removes the lead. A delete costs 6 tokens. Acts onlead Permission (capability) leads:fullVersionAvailable since the API’s base version Webhook eventNone Rate limit6 tokens SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/leads/search | Search leads by title, notes, and custom fields. | read | search:read | Current | |
The search endpoint moved to version 2 and uses search:read. A search costs 40 tokens. Acts onlead Permission (capability) search:readVersionAvailable since the API’s base version Webhook eventNone Rate limit40 tokens SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/leads/:id/convert/deal | Convert a lead into a deal. | write | leads:full | Current | |
Conversion runs asynchronously; a status endpoint reports when the deal exists. Acts onlead Permission (capability) leads:fullVersionAvailable since the API’s base version Webhook event added.dealRate limit10 tokens SourceOfficial documentation ↗ | ||||||
NotesMethods for working with notes attached to deals, persons, and organizations.4 | ||||||
| GET | /api/v1/notes | List notes attached to deals, persons, and organizations. | read | deals:read | Current | |
Notes stay on version 1 and are reachable under the deals and contacts read scopes. Acts onnote Permission (capability) deals:readVersionAvailable since the API’s base version Webhook eventNone Rate limit20 tokens SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/notes | Create a note on a deal, person, or organization. | write | deals:full | Current | |
Needs the full scope of the record the note attaches to, like deals:full or contacts:full. Acts onnote Permission (capability) deals:fullVersionAvailable since the API’s base version Webhook eventNone Rate limit10 tokens SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/notes/:id | Update a note's content. | write | deals:full | Current | |
Notes are version 1, which uses PUT, not PATCH. Acts onnote Permission (capability) deals:fullVersionAvailable since the API’s base version Webhook eventNone Rate limit10 tokens SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/notes/:id | Delete a note. | write | deals:full | Current | |
Removes the note. A delete costs 6 tokens. Acts onnote Permission (capability) deals:fullVersionAvailable since the API’s base version Webhook eventNone Rate limit6 tokens SourceOfficial documentation ↗ | ||||||
Pipelines & stagesMethods for reading the pipelines and stages a deal moves through.2 | ||||||
| GET | /api/v2/pipelines | List pipelines, the named sequences of stages a deal moves through. | read | deals:read | Current | |
Read-only, reachable under the deals read scope. Acts onpipeline Permission (capability) deals:readVersionIntroduced 2024-12-02 Webhook eventNone Rate limit20 tokens SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/stages | List stages, the steps within a pipeline. | read | deals:read | Current | |
Read-only. Creating or changing stages instead needs the admin scope. Acts onstage Permission (capability) deals:readVersionIntroduced 2024-12-02 Webhook eventNone Rate limit20 tokens SourceOfficial documentation ↗ | ||||||
Pipedrive can notify an app when something changes in an account, like a deal being added or a person being updated. It sends a POST describing the action and the object that changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
added.deal | A deal was created. The payload carries the new deal record. | /api/v2/deals |
updated.deal | A deal changed, like a stage move, a value change, or a status change to won or lost. | /api/v2/deals/:id |
deleted.deal | A deal was deleted. | /api/v2/deals/:id |
added.person | A person (contact) was created. | /api/v2/persons |
updated.person | A person (contact) changed. | /api/v2/persons/:id |
added.organization | An organization (company) was created. | /api/v2/organizations |
updated.organization | An organization (company) changed. | /api/v2/organizations/:id |
added.activity | An activity, like a call, meeting, or task, was created. | /api/v2/activities |
updated.activity | An activity changed, for example it was marked done. | /api/v2/activities/:id |
Pipedrive limits API use two ways at once: a shared daily budget measured in tokens, where each call costs an amount set by how heavy it is, and a short burst ceiling on how many requests one user can make every two seconds.
Pipedrive limits API use by a shared daily token budget rather than a flat request count. The budget is 30,000 base tokens multiplied by the plan (Lite 1x, Growth 2x, Premium 5x, Ultimate 7x) and by the number of seats, plus any purchased top-ups, and it resets at midnight in the server's timezone. Each call costs tokens by weight: a single read costs 2, a list 20, an update 10, a delete 6, and a search 40, and version 2 methods cost less than version 1. On top of the daily budget, a per-user burst limit caps requests in a rolling two-second window, from 20 per window on Lite up to 120 on Ultimate for API-token apps and higher for OAuth apps, with the Search API held to 10 per two seconds on every plan. Exhausting the daily budget or the burst window returns HTTP 429.
Version 2 list endpoints use cursor pagination: a response returns a next_cursor, which the next request passes back as the cursor parameter, with limit setting the page size. This replaces the offset-based pagination of version 1, which used start and limit. Search endpoints return ranked matches and page the same cursor way in version 2.
The daily token budget, not a row count, is the real ceiling on how much can be read, since each list and search call deducts its token cost from the shared budget. The two-second burst window is the short-term cap. Webhook deliveries are retried at 3, 30, and 150 seconds, and a webhook that fails 10 times is paused for 30 minutes.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request | The request was malformed or a parameter was invalid. The body returns success:false with an error and error_info message. | Read the error and error_info, fix the parameters, and resend. The request is not retryable as-is. |
| 401 | unauthorized | No valid token was provided, or the OAuth access token expired (it lasts 60 minutes). | Refresh the OAuth access token with the refresh token, or check the API token, then retry. |
| 403 | forbidden | The token lacks the scope or permission for this request, or an account limit was hit (the code reads feature_capping_*_limit). | Grant the needed scope, use a token whose user has the permission, or address the account limit. |
| 404 | not_found | The requested object does not exist, or is not visible to this token. | Verify the id, and confirm the token's user can see the record. |
| 410 | gone | The requested resource is no longer available, for example a deprecated version 1 endpoint that has been removed. | Move to the version 2 equivalent of the method. |
| 429 | too_many_requests | A rate limit was hit: either the shared daily token budget is exhausted or the per-user two-second burst window is over its ceiling. | Back off and retry using the x-ratelimit-reset header, and smooth request volume; if the daily budget is gone, wait for the midnight reset. |
| 500 | internal_server_error | An error on Pipedrive's side. It is rare. | Retry with backoff, and contact Pipedrive support if it persists. |
Pipedrive runs two API generations side by side. Version 2 is the current REST API, rebuilt for speed and lower token cost, and version 1 still serves the resources version 2 has not yet replaced.
Version 2 is the current REST API, rebuilt for higher performance and lower token cost. It covers deals, persons, organizations, products, pipelines, stages, and activities, with cursor-based pagination, PATCH updates, true/false booleans, RFC 3339 timestamps, and custom fields moved into a nested object.
New version 2 endpoints for the Activities API were introduced in public beta.
Production-ready version 2 endpoints for the Products, Pipelines, and Stages APIs were released.
A set of version 1 endpoints replaced by version 2 was scheduled for deprecation, with access no longer guaranteed after this date.
Prefer the version 2 method where one exists, and fall back to version 1 for resources it does not yet cover.
Pipedrive API changelog ↗Bollard AI sits between a team's AI agents and Pipedrive. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.