Deals

Revenue opportunities — service quotes, treatment plans, retainer renewals — tracked through a pipeline.

Stages

The default pipeline moves deals through NEW, CONTACTED, QUALIFIED, SCHEDULED, CONVERTED, LOST. Custom pipelines override these — see /api/pipelines/v2.

POST/api/dealsBearer token

Create a deal

Open a new deal against a contact. Stage defaults to NEW if omitted.

Required scopes:deals.write

Request body

Name	Type	Description
`title`required	`string`	Deal title. 1–200 chars.
`contactId`required	`string`	Existing contact id.
`amountCents`	`integer`	Deal value in cents. Non-negative.
`stage`	`string`	One of NEW, CONTACTED, QUALIFIED, SCHEDULED, CONVERTED, LOST.
`pipelineId`	`string`	Pipeline to attach to. Defaults to the default deal pipeline.
`expectedCloseAt`	`string`	ISO 8601 datetime.

Request body

JSON

{ "title": "Annual physical — A. Liu", "contactId": "cln…", "amountCents": 35000, "stage": "QUALIFIED" }

Responses

201 CreatedCreated.

example

{
  "id": "dl_9jw2cx…",
  "title": "Annual physical — A. Liu",
  "contactId": "cln1f8s7p0001a8l1c2k3d4e5",
  "amountCents": 35000,
  "stage": "QUALIFIED",
  "pipelineId": "pl_default",
  "ownerId": "usr_8h2c3p…",
  "expectedCloseAt": "2026-06-01T00:00:00Z",
  "createdAt": "2026-05-18T14:00:00Z"
}

422 Unprocessable EntityValidation failed.

Code samples

Shell

curl -X POST https://app.contactfollowup.com/api/deals \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Annual physical — A. Liu", "contactId": "cln…", "amountCents": 35000, "stage": "QUALIFIED" }'

GET/api/dealsBearer token

List deals

Returns the deals the caller owns or has been granted visibility for.

Required scopes:deals.read

Query parameters

Name	Type	Description
`stage`	`string`	Filter to a single stage.
`ownerId`	`string`	Filter by owning user.

Responses

200 OKMatching deals.

example

{ "deals": [{
  "id": "dl_9jw2cx…",
  "title": "Annual physical — A. Liu",
  "contactId": "cln1f8s7p0001a8l1c2k3d4e5",
  "amountCents": 35000,
  "stage": "QUALIFIED",
  "pipelineId": "pl_default",
  "ownerId": "usr_8h2c3p…",
  "expectedCloseAt": "2026-06-01T00:00:00Z",
  "createdAt": "2026-05-18T14:00:00Z"
}] }

Code samples

Shell

curl -X GET https://app.contactfollowup.com/api/deals \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json"