Deals API

Manage deals — sales opportunities with a value, status, and position in a pipeline.

Endpoints

Method	Path	Description
POST	`/deals`	Create a deal
GET	`/deals`	List deals
GET	`/deals/:id`	Get a deal
PATCH	`/deals/:id`	Update a deal
DELETE	`/deals/:id`	Delete a deal
POST	`/deals/:id/stage`	Move a deal to a new stage
GET	`/deals/:id/history`	Get stage change history
GET	`/deals/:id/activities`	List activities for a deal
GET	`/deals/:id/tasks`	List tasks for a deal

Create a deal

POST /deals

Request body

Field	Type	Required	Description
`name`	string	yes	Deal name
`pipeline_id`	string	yes	Pipeline this deal belongs to
`stage_id`	string	yes	Initial stage within the pipeline
`contact_id`	string	no	Primary contact
`company_id`	string	no	Associated company
`value`	integer	no	Deal value in cents (default 0)
`currency`	string	no	ISO 4217 currency code (default `USD`)
`status`	string	no	Status: `open`, `won`, `lost`, `stalled`
`expected_close`	datetime	no	Expected close date
`owner_id`	string	no	Assigned team member
`source`	string	no	How the deal originated
`metadata`	object	no	Arbitrary key-value data

Example

curl -X POST "$REX_URL/deals" \
  -H "X-Api-Key: $REX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Enterprise Plan",
    "pipeline_id": "pipe_01HQ...",
    "stage_id": "stg_01HQ...",
    "contact_id": "cont_01HQ...",
    "value": 500000,
    "currency": "USD"
  }'

Response

{
  "data": {
    "id": "deal_01HQ...",
    "name": "Acme Enterprise Plan",
    "pipeline_id": "pipe_01HQ...",
    "stage_id": "stg_01HQ...",
    "contact_id": "cont_01HQ...",
    "value": 500000,
    "currency": "USD",
    "status": "open",
    "days_in_stage": 0,
    "deal_age_days": 0,
    "created_at": "2026-03-16T12:00:00Z",
    "updated_at": "2026-03-16T12:00:00Z"
  }
}

List deals

GET /deals

Query parameters

Parameter	Type	Description
`cursor`	string	Pagination cursor
`limit`	integer	Results per page (default 50, max 200)
`status`	string	Filter by status: `open`, `won`, `lost`, `stalled`
`pipeline_id`	string	Filter by pipeline
`stage_id`	string	Filter by stage
`contact_id`	string	Filter by contact
`company_id`	string	Filter by company
`owner_id`	string	Filter by owner
`min_value`	integer	Minimum deal value in cents
`max_value`	integer	Maximum deal value in cents
`days_since_activity_gt`	integer	Deals with no activity for more than N days
`created_after`	datetime	Created after this time
`created_before`	datetime	Created before this time

Example

curl "$REX_URL/deals?status=open&pipeline_id=pipe_01HQ...&limit=25" \
  -H "X-Api-Key: $REX_API_KEY"

Response

{
  "data": [
    {
      "id": "deal_01HQ...",
      "name": "Acme Enterprise Plan",
      "pipeline_id": "pipe_01HQ...",
      "stage_id": "stg_01HQ...",
      "value": 500000,
      "currency": "USD",
      "status": "open",
      "days_in_stage": 3,
      "deal_age_days": 12,
      "created_at": "2026-03-04T12:00:00Z",
      "updated_at": "2026-03-16T12:00:00Z"
    }
  ],
  "has_more": false
}

Get a deal

GET /deals/:id

Example

curl "$REX_URL/deals/deal_01HQ..." \
  -H "X-Api-Key: $REX_API_KEY"

Response

{
  "data": {
    "id": "deal_01HQ...",
    "name": "Acme Enterprise Plan",
    "pipeline_id": "pipe_01HQ...",
    "stage_id": "stg_01HQ...",
    "contact_id": "cont_01HQ...",
    "company_id": "comp_01HQ...",
    "value": 500000,
    "currency": "USD",
    "status": "open",
    "expected_close": "2026-04-01T00:00:00Z",
    "owner_id": "user_01HQ...",
    "source": "inbound",
    "stage_entered_at": "2026-03-13T09:00:00Z",
    "last_activity_at": "2026-03-15T14:30:00Z",
    "days_in_stage": 3,
    "deal_age_days": 12,
    "metadata": {},
    "relationships": {
      "contact": { "type": "contact", "id": "cont_01HQ...", "name": "Ada Lovelace" },
      "company": { "type": "company", "id": "comp_01HQ...", "name": "Acme Corp" },
      "pipeline": { "type": "pipeline", "id": "pipe_01HQ...", "name": "Sales" },
      "stage": { "type": "stage", "id": "stg_01HQ...", "name": "Proposal Sent" }
    },
    "created_at": "2026-03-04T12:00:00Z",
    "updated_at": "2026-03-16T12:00:00Z"
  },
  "included": [
    { "type": "contact", "id": "cont_01HQ...", "name": "Ada Lovelace" },
    { "type": "company", "id": "comp_01HQ...", "name": "Acme Corp" }
  ]
}

Update a deal

PATCH /deals/:id

All fields from the create request body are accepted, plus loss_reason. Only provided fields are updated.

Example

curl -X PATCH "$REX_URL/deals/deal_01HQ..." \
  -H "X-Api-Key: $REX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 750000,
    "expected_close": "2026-04-15T00:00:00Z"
  }'

Response

Returns the full updated deal in the same format as Get a deal.

Delete a deal

DELETE /deals/:id

Example

curl -X DELETE "$REX_URL/deals/deal_01HQ..." \
  -H "X-Api-Key: $REX_API_KEY"

Response

204 No Content on success.

Move a deal to a new stage

POST /deals/:id/stage

Moves the deal to a new pipeline stage and creates a stage history record.

Request body

Field	Type	Required	Description
`stage_id`	string	yes	Target stage ID

Example

curl -X POST "$REX_URL/deals/deal_01HQ.../stage" \
  -H "X-Api-Key: $REX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": "stg_01HQ..."
  }'

Response

Returns the updated deal in the same format as Get a deal.

Get stage change history

GET /deals/:id/history

Returns a chronological list of stage transitions for this deal. Supports cursor and limit query parameters.

Example

curl "$REX_URL/deals/deal_01HQ.../history" \
  -H "X-Api-Key: $REX_API_KEY"

Response

{
  "data": [
    {
      "id": "sh_01HQ...",
      "deal_id": "deal_01HQ...",
      "from_stage_id": null,
      "to_stage_id": "stg_01HQ...",
      "changed_at": "2026-03-04T12:00:00Z",
      "changed_by": "user_01HQ..."
    },
    {
      "id": "sh_01HQ...",
      "deal_id": "deal_01HQ...",
      "from_stage_id": "stg_01HQ...",
      "to_stage_id": "stg_02HQ...",
      "changed_at": "2026-03-10T09:00:00Z",
      "changed_by": "user_01HQ..."
    }
  ],
  "has_more": false
}

List activities for a deal

GET /deals/:id/activities

Returns activities linked to this deal. Supports cursor and limit query parameters.

Example

curl "$REX_URL/deals/deal_01HQ.../activities" \
  -H "X-Api-Key: $REX_API_KEY"

Response

{
  "data": [
    {
      "id": "act_01HQ...",
      "type": "meeting",
      "status": "completed",
      "subject": "Demo call",
      "occurred_at": "2026-03-15T14:30:00Z",
      "created_at": "2026-03-15T14:30:00Z",
      "updated_at": "2026-03-15T14:30:00Z"
    }
  ],
  "has_more": false
}

List tasks for a deal

GET /deals/:id/tasks

Returns tasks linked to this deal. Supports cursor and limit query parameters.

Example

curl "$REX_URL/deals/deal_01HQ.../tasks" \
  -H "X-Api-Key: $REX_API_KEY"

Response

{
  "data": [
    {
      "id": "task_01HQ...",
      "title": "Send revised proposal",
      "priority": "high",
      "status": "pending",
      "due_at": "2026-03-20T17:00:00Z",
      "created_at": "2026-03-16T12:00:00Z",
      "updated_at": "2026-03-16T12:00:00Z"
    }
  ],
  "has_more": false
}

Was this page helpful?

Companies

Pipelines