Retrieve available pipelines and their stages with GET /v1/stages?pipeline_id={id} or GET /v1/pipelines to find the target stage ID
PATCH to /v1/deals/{id} with a JSON body containing stage_id set to the target stage's ID
Optionally include status (open, won, lost) and lost_reason in the same PATCH call if the move closes the deal
Confirm the move by reading back the deal with GET /v1/deals/{id} and checking stage_id and pipeline_id
Activity timelines and history entries for stage changes are created automatically by Pipedrive on a stage_id change
Known gotchas
stage_id must belong to the pipeline the deal is already in, or you must also update pipeline_id in the same request — mixing a stage from a different pipeline without updating pipeline_id results in a validation error
Moving a deal to a stage marked as won or lost stage type alone does not mark it as won/lost — set status explicitly
The Pipedrive API uses company-specific subdomain URLs (yourcompany.pipedrive.com); using a generic domain will return 404 or auth errors
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp