Pipedrive Deals & Pipeline
For sales teams on Pipedrive: find a deal or contact in seconds, see which pipeline stage it sits in, move it forward or mark it won or lost, and log the next call or meeting as an activity, all through the v2 API with cursor pagination.
Connect this API to an AI agent Browse all specs
What you can do with Pipedrive Deals & Pipeline via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /pipelines |
listPipelines | List sales pipelines |
| GET | /stages |
listStages | List pipeline stages (optionally for one pipeline) |
| GET | /deals |
listDeals | List deals filtered by stage, owner, person or status |
| POST | /deals |
createDeal | Create a deal in a pipeline stage |
| GET | /deals/search |
searchDeals | Search deals by title, notes or custom fields |
| GET | /deals/{id} |
getDeal | Get one deal with its value, stage and status |
| PATCH | /deals/{id} |
updateDeal | Update a deal: move stage, change value, mark won or lost |
| GET | /persons/search |
searchPersons | Search contacts by name, email or phone |
| GET | /persons/{id} |
getPerson | Get a contact's details |
| PATCH | /persons/{id} |
updatePerson | Update a contact's name, emails, phones or owner |
| POST | /persons |
createPerson | Add a contact person |
| GET | /organizations/search |
searchOrganizations | Search organizations by name or address |
| GET | /organizations/{id} |
getOrganization | Get an organization's details |
| GET | /activities |
listActivities | List activities (calls, meetings, tasks) for a deal, person or owner |
| POST | /activities |
createActivity | Schedule a call, meeting or task |
| PATCH | /activities/{id} |
updateActivity | Update an activity or mark it done |
| GET | /itemSearch |
searchItems | Search deals, people, organizations and more at once |
Authentication
api_key
API key — sent as the x-api-token header
Pipedrive personal API token, sent in the x-api-token header.
How to get a credential
- Sign in to Pipedrive and open your avatar menu > Personal preferences.
- Open the API tab.
- Copy Your personal API token (generate one if none is shown).
- The token acts as you: the agent sees and changes exactly what your Pipedrive user can.
Permissions used
| Access | Operations |
|---|---|
| Read deals, pipelines and stages | listPipelines, listStages, listDeals, searchDeals, getDeal |
| Write deals | createDeal, updateDeal |
| Read / write contacts | searchPersons, getPerson, createPerson, updatePerson, searchOrganizations, getOrganization |
| Read / write activities | listActivities, createActivity, updateActivity |
| Search | searchItems |
For a marketplace app using OAuth instead, the matching scopes are deals:read/deals:full, contacts:read/contacts:full, activities:read/activities:full and search:read.
Common errors
| Status | Meaning | Fix |
|---|---|---|
| 401 | Token missing, wrong or regenerated | Copy the current token from Personal preferences > API |
| 403 | Your Pipedrive user lacks permission for that item or feature | Ask an admin for access or use an account that owns the record |
| 400 | Invalid field, e.g. unknown stage_id or wrong date format | Check ids with listStages / listPipelines; dates are YYYY-MM-DD |
| 429 | Rate limit (token-based daily budget and burst limit) | Wait and retry with backoff; prefer search over listing everything |
Store the token as a VX Agents credential (API key in header) so it is never pasted into chats or prompts.
Usage guide
Setup
- Credential: your Pipedrive personal API token (Personal preferences > API), stored as a VX Agents API-key credential. It acts as your Pipedrive user, so the agent sees what you see.
- Worth pinning: the
pipeline_idyou work in (fromlistPipelines) and your ownowner_idif the agent should only touch your deals.
Work the pipeline
listPipelines, thenlistStageswithpipeline_idto learn the stage ids and their order.- Find the record:
searchDeals/searchPersons/searchOrganizationswithterm(2+ characters), orsearchItemsto look across all types at once. getDealfor value, currency,stage_id,status(open, won, lost) and the linkedperson_id/org_id.listActivitieswithdeal_id(orperson_id) to see what already happened and what is planned.- Propose the change, show it to the user and get confirmation, then:
- move or close the deal:
updateDealwithstage_id, orstatus=won/lost(+lost_reason); - log the next step:
createActivitywithsubject,type(call, meeting, task...),due_date,due_time,deal_id; - mark a step complete:
updateActivitywithdone= true.
- move or close the deal:
- New lead? Search first to avoid duplicates, then
createPerson(name, emails, phones) andcreateDeal(title, value, currency,person_id,stage_id).
Good to know
- These are Pipedrive API v2 endpoints. Lists use cursor pagination: pass
limit(max 500) and thenext_cursorfromadditional_dataascursor. - Dates are
YYYY-MM-DDand activity timesHH:MM; timestamps in responses are RFC 3339. - Ids are integers. Custom fields appear under
custom_fieldskeyed by a 40-character field hash; request them withcustom_fieldsonlistDeals. - Emails and phones on a person are arrays of
{value, primary, label}. - Changing deal value, stage or status and editing contacts changes customer data: confirm first. This spec has no delete operations.
- Rate limits use a daily token budget per company plus a burst limit; back off on 429 and prefer search over full listings.
Source: Pipedrive API reference (https://developers.pipedrive.com/docs/api/v1), checked 2026-10-16.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Pipedrive Deals & Pipeline” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.