List deals
GET /v1/deals: Returns paginated deals. Filter by pipeline_id, stage_id, owner_id, status (open/won/lost), value range, and close date range. Sort by value, created_at, updated_at, or expected_close_date.
Create a deal
POST /v1/deals: requires name, pipeline_id. Optional: value, currency, expected_close_date, owner_id, contact_ids (array), and custom fields. The deal is created in the first stage of the pipeline unless stage_id is specified.
Update a deal
PATCH /v1/deals/:id: Update any deal field. To move a deal between stages, update stage_id. Stage changes are automatically logged to the deal timeline.
Move stage
PUT /v1/deals/:id/stage: Dedicated endpoint for stage transitions. Body contains { "stage_id": "stage_abc123", "reason": "optional note" }. Returns the updated deal and the timeline entry created for the transition.
Delete a deal
DELETE /v1/deals/:id: Soft-deletes the deal. Associated contacts are not affected. The deal can be recovered from Settings → Trash within 30 days.