API v1: Deals
List, create and update deals, with optimistic locking and pipeline/stage validation.
Requires the deals:read / deals:write scopes.
List deals
GET /api/v1/deals
Standard pagination (limit, cursor, sort, fields).
Create a deal
POST /api/v1/deals
Requires deal_name, stage_id, deal_type. Validates that pipeline_id/stage_id and any contact_id/property_id belong to the account. Safe to retry with the same Idempotency-Key.
{
"deal_name": "Lozenets 2-bed — Ivanov",
"pipeline_id": "...",
"stage_id": "...",
"deal_type": "buyer",
"contact_id": "...",
"property_id": "...",
"deal_value": 185000,
"currency": "EUR",
"probability": 40
}
Deal fields
| Field | Type | Notes |
|---|---|---|
deal_name | string | required, 1–255 chars |
contact_id, property_id | uuid, nullable | |
pipeline_id, stage_id | uuid | required |
deal_type | enum | buyer, seller, rental_tenant, rental_landlord |
deal_value | number, nullable | 0–999,999,999.99 |
currency | string, nullable | ISO 4217, 3 chars |
probability | integer, nullable | 0–100 |
status | enum | active, won, lost, cancelled |
expected_close_date, actual_close_date | date, nullable | |
deal_source | enum, nullable | referral, website, cold_call, walk_in, social_media, advertising, partner, portal, campaign, event, viber, facebook_ads, facebook_messenger, google_ads, website_form, client_portal, ai_conversion, exchange, other |
won_reason, lost_reason | string, nullable | set alongside status: "won" / "lost" |
version | integer | optimistic-locking counter, starts at 1 |
Get / update a deal
GET /api/v1/deals/{id}
PATCH /api/v1/deals/{id}
PATCH requires the current version in the body and supports optimistic locking: if the deal was modified by another request since you last read it, the update returns 409 Conflict instead of silently overwriting it — re-fetch and retry.
{
"version": 3,
"status": "won",
"actual_close_date": "2026-09-02",
"won_reason": "Client signed after second viewing"
}
Delete a deal
DELETE /api/v1/deals/{id}
Moves the deal to trash (204).
Poll for changes
GET /api/v1/deals/changes?since=2026-09-01T00:00:00Z
Pipelines
GET /api/v1/pipelines
Read-only. Returns all pipelines with their stages — use this to resolve pipeline_id/stage_id before creating or updating a deal.