Deals

A deal is a sales opportunity that moves through your pipeline.

Permissions: contacts:read and contacts:write.

The deal object

{
  "id": 15,
  "name": "Acme Corp Enterprise Plan",
  "amount": 5000.0,
  "currency": "EUR",
  "expected_close_date": "2026-06-30",
  "notes": "Decision maker: Alice Martin",
  "lost_reason": null,
  "won_at": null,
  "lost_at": null,
  "is_won": false,
  "is_lost": false,
  "stage_id": 1,
  "contact_id": 7,
  "company_id": 3,
  "assigned_to": 1,
  "stage": { /* DealStage */ },
  "contact": { /* Contact */ },
  "company": { /* Company */ },
  "assigned_user": { "id": 1, "name": "Alice Martin", "email": "alice@acme.com" },
  "created_at": "...",
  "updated_at": "..."
}

currency is EUR, USD or GBP.

Endpoints

Method	Path	Description
GET	/crm/deals	List deals (paginated)
POST	/crm/deals	Create a deal
GET	/crm/deals/{id}	Get a deal
PUT	/crm/deals/{id}	Update a deal (partial)
DELETE	/crm/deals/{id}	Delete a deal. Returns 204.
POST	/crm/deals/{id}/won	Mark the deal as won
POST	/crm/deals/{id}/lost	Mark the deal as lost

List deals

See CRM listings for search, workspace-scoped filters, stable sorting, pagination, and a curl example.

Create a deal

Field	Rules
name	Required. Max 255 characters
stage_id	Required. A stage in your pipeline
contact_id, company_id	Records in your workspace
amount	Number ≥ 0
currency	Default EUR
expected_close_date	Date (YYYY-MM-DD)
assigned_to	The user ID of a workspace member
notes	Text

201: { "data": Deal }

Move through the pipeline

PUT /crm/deals/{id}

{ "stage_id": 2 }

The stage you move a deal to determines its won/lost state:

• moving it to an is_won stage sets won_at;
• moving it to an is_lost stage sets lost_at;
• moving it to any other stage clears both.

PUT also accepts lost_reason, up to 255 characters.

Won / lost

POST /crm/deals/{id}/won
POST /crm/deals/{id}/lost   { "reason": "Budget" }

Each call sets won_at or lost_at and moves the deal to the first is_won or is_lost stage in the pipeline.

200: { "data": Deal, "message": "Deal marked as won" }