API reference

Deals

Deals are opportunities with a value, moving through the stages of a pipeline until they are won or lost. They feed the forecast and the pipeline board in the app.

Scopes: deals:read · deals:write
Plan: Sales hub
Events: deal.*

The deal object

pipeline and stage repeat the IDs with their names, so a list can be shown without looking pipelines up. Without the Sales hub in the plan, every deal endpoint answers 403 hub_not_in_plan.

Attributes

iduuidRead-only
Unique identifier of the deal.
titlestring
Deal name.
valuenumber
Amount, in currency.
currencystring
ISO 4217 code, for example EUR. Defaults to the workspace currency.
statusenum
The outcome: open (in_progress), won, lost or paused (on_hold).
One ofin_progresswonloston_hold
pipelineobjectRead-onlyNullable
The pipeline’s ID and name; null if the deal is in no pipeline.
- iduuid
  Pipeline ID.
- namestring
  Pipeline name.
stageobjectRead-onlyNullable
The current stage; null if the deal is in no pipeline.
- iduuid
  Stage ID.
- namestring
  Stage name.
- typeenum
  Open, or closed as won or lost.
  One ofopenwonlost
pipeline_iduuidNullable
The pipeline the deal is in.
stage_iduuidNullable
The stage the deal is in. Changing it moves the deal like dragging its card in the app.
probabilityinteger
Win probability in percent, 0–100.
expected_close_datedateNullable
When the deal is expected to close. The forecast groups deals by this date.
closed_atdate-timeNullable
When the deal was won or lost.
forecast_categoryenumNullable
Forecast bucket. Deals without one count as pipeline in the forecast; omit leaves the deal out.
One ofcommitbest_casepipelineomit
loss_reasonstringNullable
Why the deal was lost, as free text — the app suggests price, competitor, no_decision, bad_fit, timing, budget, champion_left, internal and other.
competitorstringNullable
Who the deal was lost to, when known.
contact_iduuidNullable
The main contact.
company_iduuidNullable
The company.
owner_iduuid
The user who owns the record. On create it defaults to the API key’s owner. See Users.
custom_fieldsobject
Custom-field values keyed by field key. Updates merge into the stored values; send null for a key to clear it. See Custom fields.
created_atdate-timeRead-only
When the record was created (UTC).
updated_atdate-timeRead-only
When the record last changed (UTC).

The deal object

{
  "id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
  "title": "Northwind Analytics — annual plan",
  "value": 24000,
  "currency": "EUR",
  "status": "in_progress",
  "pipeline": {
    "id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
    "name": "New business"
  },
  "stage": {
    "id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
    "name": "Proposal",
    "type": "open"
  },
  "pipeline_id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
  "stage_id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
  "probability": 60,
  "expected_close_date": "2026-11-27",
  "closed_at": null,
  "forecast_category": "best_case",
  "loss_reason": null,
  "competitor": null,
  "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
  "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
  "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
  "custom_fields": {
    "seats": 40
  },
  "created_at": "2026-10-01T10:12:00Z",
  "updated_at": "2026-10-09T15:40:22Z"
}

Stages and outcomes

A deal sits in one stage of one pipeline. Read the pipelines for their stage IDs. A deal created without pipeline_id and stage_id lands in the first stage of the default pipeline.

Changing stage_id moves the deal exactly as dragging its card on the board does: Nextora records when it entered the stage, runs the workflows that react to the move and sends deal.stage_changed. Move it to a stage of another pipeline by sending both pipeline_id and stage_id.

status is the outcome. in_progress is open, on_hold is paused, and won and lost close the deal and send deal.won or deal.lost. Send closed_at with the outcome to record when it happened, and loss_reason and competitor when a deal is lost.

Mark a deal won

curl -X PATCH https://acme.nextora.co/api/v1/deals/8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80 \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "won",
    "stage_id": "8a6d2e4f-7c9b-4a1e-b3d5-0f2c4e6a8b39",
    "closed_at": "2026-10-10T14:03:00Z"
  }'

Response200 OK

{
  "data": {
    "id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
    "title": "Northwind Analytics — annual plan",
    "value": 24000,
    "currency": "EUR",
    "status": "won",
    "pipeline": {
      "id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
      "name": "New business"
    },
    "stage": {
      "id": "8a6d2e4f-7c9b-4a1e-b3d5-0f2c4e6a8b39",
      "name": "Won",
      "type": "won"
    },
    "pipeline_id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
    "stage_id": "8a6d2e4f-7c9b-4a1e-b3d5-0f2c4e6a8b39",
    "probability": 100,
    "expected_close_date": "2026-11-27",
    "closed_at": "2026-10-10T14:03:00Z",
    "forecast_category": "commit",
    "loss_reason": null,
    "competitor": null,
    "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "custom_fields": {
      "seats": 40
    },
    "created_at": "2026-10-01T10:12:00Z",
    "updated_at": "2026-10-10T14:03:00Z"
  }
}

Mark a deal lost

curl -X PATCH https://acme.nextora.co/api/v1/deals/8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80 \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "lost",
    "stage_id": "1d9f3b5a-6e2c-4f8d-9a7b-3c5e7f9a1b04",
    "closed_at": "2026-10-10T14:03:00Z",
    "loss_reason": "price",
    "competitor": "Contoso"
  }'

Forecast categories

forecast_category puts an open deal in a bucket of the forecast. probability is separate: the forecast uses it to weight values.

Category	Meaning
`commit`	The owner is confident the deal closes in the period.
`best_case`	It could close in the period if things go well.
`pipeline`	Open, but not yet likely in the period. Deals without a category count here.
`omit`	Left out of the forecast.

List deals

GET/api/v1/deals

Requires deals:read

Returns the deals the key’s owner can see, newest first. Filter on the fields below, combine them with q, and follow meta.next_cursor for more.

Query parameters

limitinteger
Page size, from 1 to 100.
Default50
cursorstring
The meta.next_cursor of the previous page. Omit it for the first page.
qstring
Search by title.
sortenum
The field to sort by. Any other value is a 400 validation_failed.
One ofcreated_atupdated_attitlevalueprobabilityexpected_close_dateclosed_at
Defaultcreated_at
orderenum
Sort direction.
One ofascdesc
Defaultdesc
filterstring (JSON)
An advanced filter: conditions joined with and or or. See the JSON filter.

Filters

Add ?field=value or ?field[operator]=value — operators.

statusenum
Exact match, or several values with [in].
One ofin_progresswonloston_hold
pipeline_iduuid
Exact match, or several IDs with [in].
stage_iduuid
Exact match, or several IDs with [in].
contact_iduuid
Exact match, or several IDs with [in].
company_iduuid
Exact match, or several IDs with [in].
owner_iduuid
Exact match, or several IDs with [in].
valuenumber
Exact, or a range with [gt], [gte], [lt] and [lte].
expected_close_datedate
A date (YYYY-MM-DD). Exact, or a range with [gt], [gte], [lt] and [lte].
created_atdate-time
An ISO 8601 timestamp. Use a range: [gt], [gte], [lt], [lte].
updated_atdate-time
An ISO 8601 timestamp. Use a range: [gt], [gte], [lt], [lte].
closed_atdate-time
An ISO 8601 timestamp. Use a range: [gt], [gte], [lt], [lte].

Returns

A list of deal objects and meta. meta.next_cursor is null on the last page.

GET/api/v1/deals

curl -G https://acme.nextora.co/api/v1/deals \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -d status=in_progress \
  -d 'value[gte]=10000' \
  -d sort=expected_close_date \
  -d order=asc \
  -d limit=20

Response200 OK

{
  "data": [
    {
      "id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
      "title": "Northwind Analytics — annual plan",
      "value": 24000,
      "currency": "EUR",
      "status": "in_progress",
      "pipeline": {
        "id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
        "name": "New business"
      },
      "stage": {
        "id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
        "name": "Proposal",
        "type": "open"
      },
      "pipeline_id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
      "stage_id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
      "probability": 60,
      "expected_close_date": "2026-11-27",
      "closed_at": null,
      "forecast_category": "best_case",
      "loss_reason": null,
      "competitor": null,
      "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
      "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
      "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
      "custom_fields": {
        "seats": 40
      },
      "created_at": "2026-10-01T10:12:00Z",
      "updated_at": "2026-10-09T15:40:22Z"
    }
  ],
  "meta": {
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6IjNmMWM5YTdlIiwiY3JlYXRlZF9hdCI6IjIwMjYtMDktMTRUMDk6MzA6MDBaIn0"
  }
}

Create a deal

POST/api/v1/deals

Requires deals:write

Creates a deal. It goes through the same path as the app, so workflows, the activity log and webhooks behave as they do for a deal created by hand.

Body parameters

titlestringRequired
Deal name.
valuenumber
Amount, in currency.
Default0
currencystring
ISO 4217 code, for example EUR. Defaults to the workspace currency.
statusenum
The outcome to start with — usually left out. won or lost creates a closed deal.
One ofin_progresswonloston_hold
Defaultin_progress
pipeline_iduuidNullable
The pipeline. Defaults to the default pipeline.
stage_iduuidNullable
The stage. Defaults to the first stage of the pipeline.
probabilityinteger
Win probability in percent, 0–100. 0 is kept as 0.
expected_close_datedateNullable
When the deal is expected to close. The forecast groups deals by this date.
closed_atdate-timeNullable
When the deal was won or lost.
forecast_categoryenumNullable
Forecast bucket. Deals without one count as pipeline in the forecast; omit leaves the deal out.
One ofcommitbest_casepipelineomit
loss_reasonstringNullable
Why the deal was lost, as free text — the app suggests price, competitor, no_decision, bad_fit, timing, budget, champion_left, internal and other.
competitorstringNullable
Who the deal was lost to, when known.
contact_iduuidNullable
The main contact.
company_iduuidNullable
The company.
owner_iduuid
The user who owns the record. On create it defaults to the API key’s owner. See Users.
custom_fieldsobject
Custom-field values keyed by field key. Updates merge into the stored values; send null for a key to clear it. See Custom fields.

Returns

The new deal, with 201 Created.

POST/api/v1/deals

curl -X POST https://acme.nextora.co/api/v1/deals \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Northwind Analytics — annual plan",
    "value": 24000,
    "currency": "EUR",
    "pipeline_id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
    "stage_id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
    "probability": 60,
    "expected_close_date": "2026-11-27",
    "forecast_category": "best_case",
    "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "custom_fields": {
      "seats": 40
    }
  }'

Response201 Created

{
  "data": {
    "id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
    "title": "Northwind Analytics — annual plan",
    "value": 24000,
    "currency": "EUR",
    "status": "in_progress",
    "pipeline": {
      "id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
      "name": "New business"
    },
    "stage": {
      "id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
      "name": "Proposal",
      "type": "open"
    },
    "pipeline_id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
    "stage_id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
    "probability": 60,
    "expected_close_date": "2026-11-27",
    "closed_at": null,
    "forecast_category": "best_case",
    "loss_reason": null,
    "competitor": null,
    "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "custom_fields": {
      "seats": 40
    },
    "created_at": "2026-10-01T10:12:00Z",
    "updated_at": "2026-10-01T10:12:00Z"
  }
}

Retrieve a deal

GET/api/v1/deals/{id}

Requires deals:read

Returns one deal by ID.

Path parameters

iduuidRequired
The deal’s ID.

Returns

The deal. 404 not_found when it does not exist or the key’s owner cannot see it.

GET/api/v1/deals/{id}

curl https://acme.nextora.co/api/v1/deals/8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80 \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
    "title": "Northwind Analytics — annual plan",
    "value": 24000,
    "currency": "EUR",
    "status": "in_progress",
    "pipeline": {
      "id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
      "name": "New business"
    },
    "stage": {
      "id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
      "name": "Proposal",
      "type": "open"
    },
    "pipeline_id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
    "stage_id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
    "probability": 60,
    "expected_close_date": "2026-11-27",
    "closed_at": null,
    "forecast_category": "best_case",
    "loss_reason": null,
    "competitor": null,
    "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "custom_fields": {
      "seats": 40
    },
    "created_at": "2026-10-01T10:12:00Z",
    "updated_at": "2026-10-09T15:40:22Z"
  }
}

Update a deal

PATCH/api/v1/deals/{id}

Requires deals:write

Changes the fields you send and leaves the rest as they are; PUT does the same as PATCH. A new stage_id moves the deal like a drag on the board — see stages and outcomes.

Path parameters

iduuidRequired
The deal’s ID.

Body parameters

titlestring
Deal name.
valuenumber
Amount, in currency.
currencystring
ISO 4217 code, for example EUR. Defaults to the workspace currency.
statusenum
The outcome: open (in_progress), won, lost or paused (on_hold).
One ofin_progresswonloston_hold
pipeline_iduuidNullable
The pipeline the deal is in.
stage_iduuidNullable
The stage the deal is in. Changing it moves the deal like dragging its card in the app.
probabilityinteger
Win probability in percent, 0–100.
expected_close_datedateNullable
When the deal is expected to close. The forecast groups deals by this date.
closed_atdate-timeNullable
When the deal was won or lost.
forecast_categoryenumNullable
Forecast bucket. Deals without one count as pipeline in the forecast; omit leaves the deal out.
One ofcommitbest_casepipelineomit
loss_reasonstringNullable
Why the deal was lost, as free text — the app suggests price, competitor, no_decision, bad_fit, timing, budget, champion_left, internal and other.
competitorstringNullable
Who the deal was lost to, when known.
contact_iduuidNullable
The main contact.
company_iduuidNullable
The company.
owner_iduuid
The user who owns the record. On create it defaults to the API key’s owner. See Users.
custom_fieldsobject
Custom-field values keyed by field key. Updates merge into the stored values; send null for a key to clear it. See Custom fields.

Returns

The updated deal.

PATCH/api/v1/deals/{id}

curl -X PATCH https://acme.nextora.co/api/v1/deals/8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80 \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": "7c3f5a9e-4d1b-4e8c-a2f6-9b0d3e5a7c18",
    "probability": 80
  }'

Response200 OK

{
  "data": {
    "id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
    "title": "Northwind Analytics — annual plan",
    "value": 24000,
    "currency": "EUR",
    "status": "in_progress",
    "pipeline": {
      "id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
      "name": "New business"
    },
    "stage": {
      "id": "7c3f5a9e-4d1b-4e8c-a2f6-9b0d3e5a7c18",
      "name": "Negotiation",
      "type": "open"
    },
    "pipeline_id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
    "stage_id": "7c3f5a9e-4d1b-4e8c-a2f6-9b0d3e5a7c18",
    "probability": 80,
    "expected_close_date": "2026-11-27",
    "closed_at": null,
    "forecast_category": "best_case",
    "loss_reason": null,
    "competitor": null,
    "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "custom_fields": {
      "seats": 40
    },
    "created_at": "2026-10-01T10:12:00Z",
    "updated_at": "2026-10-10T11:02:37Z"
  }
}

Delete a deal

DELETE/api/v1/deals/{id}

Requires deals:write

Moves the deal to the workspace Trash, as deleting it in the app does. It disappears from lists; restore it to bring it back.

Path parameters

iduuidRequired
The deal’s ID.

Returns

{ "data": { "id": "…", "deleted": true } }. 404 not_found when there is nothing to delete.

DEL/api/v1/deals/{id}

curl -X DELETE https://acme.nextora.co/api/v1/deals/8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80 \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
    "deleted": true
  }
}

Restore a deal

POST/api/v1/deals/{id}/restore

Requires deals:write

Brings a deal back from Trash, with its fields and links as they were.

Path parameters

iduuidRequired
The deal’s ID.

Returns

The restored deal.

POST/api/v1/deals/{id}/restore

curl -X POST https://acme.nextora.co/api/v1/deals/8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80/restore \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "8f2d6c1a-4b7e-4f0a-9c3d-2e1b5a6f7c80",
    "title": "Northwind Analytics — annual plan",
    "value": 24000,
    "currency": "EUR",
    "status": "in_progress",
    "pipeline": {
      "id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
      "name": "New business"
    },
    "stage": {
      "id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
      "name": "Proposal",
      "type": "open"
    },
    "pipeline_id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
    "stage_id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
    "probability": 60,
    "expected_close_date": "2026-11-27",
    "closed_at": null,
    "forecast_category": "best_case",
    "loss_reason": null,
    "competitor": null,
    "contact_id": "3f1c9a7e-2b4d-4c8e-9f60-1a2b3c4d5e6f",
    "company_id": "2b7e4c9a-5d1f-4a8e-9b3c-7f0a1d2e4c56",
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "custom_fields": {
      "seats": 40
    },
    "created_at": "2026-10-01T10:12:00Z",
    "updated_at": "2026-10-09T15:40:22Z"
  }
}