Deals API

The Deals API manages sales-pipeline deals. Each deal lives in a pipeline stage; create, move, update, and close deals programmatically.

REST API. Authenticated with Authorization: Bearer rk_live_…. Successful responses are wrapped in { "data": … }.

Required Scopes

Deal Object

{
  id: string;
  organization_id: string;
  pipeline_id: string;
  stage_id: string;
  name: string;
  amount?: number | null;
  currency: string;               // default "USD"
  status: 'open' | 'won' | 'lost';
  priority: 'low' | 'medium' | 'high' | 'urgent';
  customer_id?: string | null;
  owner_id?: string | null;
  expected_close_date?: string | null;
  notes?: string | null;
  tags: string[];
  position: number;
  won_at?: string | null;
  lost_at?: string | null;
  created_at: string;
  // List/get responses embed: customer, owner, stage summaries
}

Pipelines and stages are managed in the dashboard. Reference an existing pipeline_id + stage_id when creating a deal; both must belong to your organization.

List Deals

GET /api/v1/deals

Scope: deals:read

Query params: status (open|won|lost|all, default open), pipeline_id, stage_id, customer_id, owner_id, search (matches name), limit, offset.

curl "https://crm.switchlabs.dev/api/v1/deals?status=open&pipeline_id=PIPE_ID" \
  -H "Authorization: Bearer rk_live_xxx"

Get Deal

GET /api/v1/deals/:id — single deal with embedded customer, owner, and stage. Scope: deals:read.

Create Deal

POST /api/v1/deals

Scope: deals:write

Body:

{
  pipeline_id: string;    // required, UUID — must belong to your org
  stage_id: string;       // required, UUID — must belong to the pipeline
  name: string;           // required, 1-200 chars
  amount?: number;
  currency?: string;      // default "USD"
  expected_close_date?: string;
  customer_id?: string;
  owner_id?: string;
  priority?: 'low' | 'medium' | 'high' | 'urgent';  // default "medium"
  notes?: string;
  tags?: string[];
}

curl -X POST "https://crm.switchlabs.dev/api/v1/deals" \
  -H "Authorization: Bearer rk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "pipeline_id": "PIPE_ID", "stage_id": "STAGE_ID", "name": "Acme — fleet pilot", "amount": 12000, "customer_id": "CUST_ID" }'

Returns 201. If stage_id doesn't belong to pipeline_id in your org, returns 400.

Update Deal

PATCH /api/v1/deals/:id

Scope: deals:write

Update any of name, amount, currency, expected_close_date, customer_id, owner_id, stage_id, priority, notes, tags, position, status. Setting status to won or lost stamps won_at / lost_at.

curl -X PATCH "https://crm.switchlabs.dev/api/v1/deals/DEAL_ID" \
  -H "Authorization: Bearer rk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "stage_id": "NEXT_STAGE_ID", "status": "won" }'

Delete Deal

DELETE /api/v1/deals/:id — soft-delete. Returns 204. Scope: deals:write.

See also: Customers · Sequences