API Reference

Deals and pipeline

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.

Overview

MethodPathDescription
GET/api/v1/pipelineThe pipeline: its currency, its stages in order, and the team.
GET/api/v1/dealsThe account's deals, newest first, with filters.
GET/api/v1/deals/{id}One deal, with its contacts.
POST/api/v1/dealsCreate 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.

The pipeline

GET/api/v1/pipeline
FieldTypeDescription
idstring (uuid)The pipeline's id.
currencystringEvery deal's currency, like USD.
stagesarrayIn 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).
teamarrayThe people a deal or a task can be given to: email and name. Owners and assignees are named by this email.

The deal object

FieldTypeDescription
idstring (uuid)The deal's id.
namestringIts name, up to 200 characters.
stage_id / stagestringIts stage's id, and the stage's name now.
statusstringopen, won or lost: follows from its stage.
amount_minornumber | nullIts amount in the smallest unit of currency: 1250.00 USD is 125000.
currencystringThe pipeline's currency.
close_datestring | nullWhen it is expected to close, YYYY-MM-DD.
owner_emailstring | nullIts owner in the team, by their email.
company_id / company_namestring | nullIts company.
sourcestringHow 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_atstringWhen it entered the stage it is in.
last_reply_atstring | nullWhen one of its contacts last replied to an email of yours, with reply tracking on.
replyobject | nullFor a deal made from a reply: from_email, received_at, and, when the account sorts replies, label and summary. Never the reply's words.
contactsarrayOn one deal and a write's answer: id, email, first_name, last_name and is_main, the main contact first.
lost_reason / closed_atstring | nullOn one deal and a write's answer: why it was lost, and when it was won or lost.
created_atstringWhen it was made.
updated_atstringSend it back exactly as read when you change or move the deal.

List and read

GET/api/v1/deals
ParameterTypeDescription
statusstringopen, won or lost.
stage_idstringDeals in this stage.
company_idstringDeals of this company.
contact_idstringDeals this contact is on, main contact or not.
owner_emailstringDeals this team member owns.
limit / cursornumber / string1 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.

Create a deal

POST/api/v1/deals
FieldTypeDescription
namestringRequired, up to 200 characters.
stage_idstringThe stage to put it in. Left out: the first open stage.
amount_minornumber | nullA whole number in the smallest unit of the pipeline's currency.
close_datestring | nullYYYY-MM-DD.
owner_emailstring | nullSomeone in the team (GET /pipeline lists them).
company_idstring | nullIts company.
contact_idsstring[]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.

import { PristineSend } from "pristinesend"

const ps = new PristineSend(process.env.PRISTINESEND_API_KEY!)

const pipeline = await ps.pipeline.get()
const { data: deal } = await ps.deals.create({
  name: "Acme, 20 seats",
  stage_id: pipeline.stages[0].id,
  amount_minor: 480000, // 4,800.00 in the pipeline's currency
  company_id: acmeId,
  contact_ids: [janeId],
})

Change or move a deal

PATCH/api/v1/deals/{id}

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:

  • Changes its fields: name, amount_minor, close_date, owner_email and company_id; null clears one.
  • Moves it: 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.

const deal = await ps.deals.get(dealId)

// Move it: stage_id, with lost_reason when the stage is Lost.
await ps.deals.update(dealId, { updated_at: deal.updated_at, stage_id: wonStageId })
A create or a move can send email. An automation started by “A deal enters a stage” runs for the deal's main contact when you create the deal in that stage or move it there, exactly as when a person does it on the board. See Automations on the pipeline.

Delete a deal

DELETE/api/v1/deals/{id}

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.

Test keys

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.

Errors

StatuscodeWhen
400missing_fieldA new deal with no name, or a change with no updated_at.
400invalid_fieldA 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).
400invalid_requestThe body is not a JSON object, a change moves the deal and changes its fields at once, or names nothing to change.
403insufficient_scopeThe key lacks crm:read (reading) or crm:write (writing).
403crm_not_enabledThe account hasn't turned the CRM on, or has no pipeline yet (Pipeline, in PristineSend).
403live_key_requiredA test key creating a deal or moving one: see Test keys.
404not_foundThis account has no deal with that id.
409conflictThe deal changed after the updated_at you sent: read it again and make your change on what it holds now.
429rate_limited120 CRM changes a minute per account. Retry after Retry-After.
503service_unavailableA 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.