The deals on your CRM's pipeline. Read the pipeline once for its stages and team, then create and move deals. A deal entering a stage can start an automation; nothing else here sends email.
| Method | Path | Description |
|---|---|---|
GET | /api/v1/pipeline | The pipeline: its currency, its stages in order, and the team. |
GET | /api/v1/deals | The account's deals, newest first, with filters. |
GET | /api/v1/deals/{id} | One deal, with its contacts. |
POST | /api/v1/deals | Create a deal. |
PATCH | /api/v1/deals/{id} | Change a deal's fields, or move it to another stage. |
DELETE | /api/v1/deals/{id} | Delete a deal and its history. |
Reading needs the crm:read scope, writing crm:write. The account needs the CRM turned on and a pipeline, which someone in the team sets up once in PristineSend (Pipeline). The stages themselves are set there too: the API reads them and never changes them. Changes count against the CRM's limit of 120 a minute per account. Send an Idempotency-Key on a create, so a retried request cannot make a second deal.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | The pipeline's id. |
currency | string | Every deal's currency, like USD. |
stages | array | In order: the open stages, then Won and Lost. Each has id, name, kind (open, won or lost), position and rot_days (days before a card says it is going cold, or null). |
team | array | The people a deal or a task can be given to: email and name. Owners and assignees are named by this email. |
| Field | Type | Description |
|---|---|---|
id | string (uuid) | The deal's id. |
name | string | Its name, up to 200 characters. |
stage_id / stage | string | Its stage's id, and the stage's name now. |
status | string | open, won or lost: follows from its stage. |
amount_minor | number | null | Its amount in the smallest unit of currency: 1250.00 USD is 125000. |
currency | string | The pipeline's currency. |
close_date | string | null | When it is expected to close, YYYY-MM-DD. |
owner_email | string | null | Its owner in the team, by their email. |
company_id / company_name | string | null | Its company. |
source | string | How it was made: manual, import, api, reply (a reply put it on the pipeline), automation or booking (a meeting booked on one of your booking pages or through Calendly or Cal.com). |
stage_entered_at | string | When it entered the stage it is in. |
last_reply_at | string | null | When one of its contacts last replied to an email of yours, with reply tracking on. |
reply | object | null | For a deal made from a reply: from_email, received_at, and, when the account sorts replies, label and summary. Never the reply's words. |
contacts | array | On one deal and a write's answer: id, email, first_name, last_name and is_main, the main contact first. |
lost_reason / closed_at | string | null | On one deal and a write's answer: why it was lost, and when it was won or lost. |
created_at | string | When it was made. |
updated_at | string | Send it back exactly as read when you change or move the deal. |
| Parameter | Type | Description |
|---|---|---|
status | string | open, won or lost. |
stage_id | string | Deals in this stage. |
company_id | string | Deals of this company. |
contact_id | string | Deals this contact is on, main contact or not. |
owner_email | string | Deals this team member owns. |
limit / cursor | number / string | 1 to 100 (50 when left out), and next_cursor from the page before. |
The answer is a page, newest first (Pagination). A deal in the list leaves out its contacts; GET /api/v1/deals/{id} has them. A deal's history, notes and tasks are on its timeline.
| Field | Type | Description |
|---|---|---|
name | string | Required, up to 200 characters. |
stage_id | string | The stage to put it in. Left out: the first open stage. |
amount_minor | number | null | A whole number in the smallest unit of the pipeline's currency. |
close_date | string | null | YYYY-MM-DD. |
owner_email | string | null | Someone in the team (GET /pipeline lists them). |
company_id | string | null | Its company. |
contact_ids | string[] | Its contacts, the main contact first, at most 50. |
The answer is 201 with the deal. When the deal was saved but reading it back failed, it is still 201, with its id and a warning: read it with GET, and don't create it again. Its history records who made it: an API key by its name, a connected AI by the person who connected it.
Every change names the deal's updated_at exactly as you read it, and lands only while the deal is still that version: a deal someone moved or edited since is refused with 409 conflict, never overwritten. A change does one of two things:
name, amount_minor, close_date, owner_email and company_id; null clears one.stage_id, with lost_reason (up to 500 characters) for the Lost stage. A move to Won or Lost closes the deal; a move back to an open stage reopens it.Send them in two requests, reading the deal again between them, since each change gives it a new updated_at. A deal's contacts are changed in PristineSend.
Deletes the deal and its history, notes and tasks. Its contacts and company stay. The answer is { data: { id, deleted: true } }. A deleted deal cannot be brought back.
The CRM has no test copy: a ps_test_ key reads and writes your real records. It may not create a deal or move one to another stage, which is refused with 403 live_key_required, because a deal entering a stage can start an automation that sends real email, and a test key never sends. Use a ps_live_ key for those.
| Status | code | When |
|---|---|---|
400 | missing_field | A new deal with no name, or a change with no updated_at. |
400 | invalid_field | A field or parameter the endpoint does not take, a stage that is not the pipeline's, an owner outside the team, or a contact or company that isn't the account's (param names it). |
400 | invalid_request | The body is not a JSON object, a change moves the deal and changes its fields at once, or names nothing to change. |
403 | insufficient_scope | The key lacks crm:read (reading) or crm:write (writing). |
403 | crm_not_enabled | The account hasn't turned the CRM on, or has no pipeline yet (Pipeline, in PristineSend). |
403 | live_key_required | A test key creating a deal or moving one: see Test keys. |
404 | not_found | This account has no deal with that id. |
409 | conflict | The deal changed after the updated_at you sent: read it again and make your change on what it holds now. |
429 | rate_limited | 120 CRM changes a minute per account. Retry after Retry-After. |
503 | service_unavailable | A read or write behind the request failed: send the same request again. A change lands once however often it is sent. |
See Error codes for the envelope and the full list.