Skip to main content
With the Pipelines battery, the API reaches the same pipelines and deals your team works on the board. Create a deal when a lead arrives on your website, move it as your own systems learn more, mark it won when the order is paid, and add notes your team will see on the deal’s page. A deal changed through the API obeys the rules a deal dragged on the board does, and its history names the key that changed it — API · <key name>.
  • The endpoints are under /v1/crm/…. They exist when the account’s plan includes Pipelines; otherwise every one answers 404 module_off.
  • Pipelines and stages have whole-number ids; deals have string ids.
  • Values are whole numbers in the currency’s minor unit: value_minor 12500000 with currency INR is ₹1,25,000.

​
Scopes

See Keys and scopes for giving a key its scopes.

​
Pipelines and stages

​
Deals

A new deal from your website might be:
Give it a contact and the contact’s messages, on any channel, show on the deal and in its timeline.

​
Winning, losing and reopening

A deal’s status is open, won or lost. A pipeline can have one won stage and one lost stage — its closing stages, marked by their outcome. A new pipeline has a won stage (Won) and no lost stage; add one with "outcome": "lost" if you want lost deals in a column of their own.
  • Moving a deal into a closing stage closes it: into the won stage wins it, into the lost stage loses it, and closed_at is set.
  • Marking a deal won or lost moves it to the pipeline’s won or lost stage, when it has one.
  • Reopening: moving a closed deal out of its closing stage opens it again. Setting status to open on a deal in a closing stage moves it back to the last ordinary stage.
  • Sending stage and status together moves the deal and sets that status, as given.
  • A deal created in a closing stage starts closed.
Making a stage the won (or lost) stage turns the stage that held that outcome into an ordinary one. Deals already in it keep their status; the rule applies to moves from then on.

​
Removing stages and pipelines

  • A stage that holds deals is deleted only with move_to, another stage of the same pipeline. Each deal moves there first, by the rules above — into a closing stage closes it — and each move sends its own webhook event. A pipeline keeps at least one stage.
  • A pipeline with open deals can’t be deleted: the request is refused with 409 invalid_state. Win, lose or move its open deals first. Its won and lost deals are deleted with it, without a deal.deleted event for each.

​
Hearing about changes

Rather than asking, subscribe a webhook endpoint to the deal.* events. They fire for every change, wherever it was made — the board, an AI agent or the API. Each change sends one event: a change of status (deal.won, deal.lost, deal.reopened) outranks a move (deal.stage_changed), which outranks the rest (deal.updated). Dragging a deal into the won stage sends deal.won, not deal.stage_changed as well. Each event carries the deal, as deal, in the shape GET …/deals/{deal_id} answers, and changed — the names of the fields that changed:
deal.deleted carries only the deal’s id and title, as deal.
Notes don’t send events. Read a deal’s notes with GET …/notes, or its whole story with GET …/timeline.