API reference

Pipelines

Pipelines hold the stages deals move through. Read them to get the stage IDs you need to create or move deals; change them in the app.

Scope: deals:read
Plan: Sales hub
Access: Read-only

The pipeline object

Stages come in board order. A stage’s type says whether a deal in it is open or closed — the names are the workspace’s own.

Attributes

iduuidRead-only
Unique identifier of the pipeline.
namestring
Pipeline name.
is_defaultboolean
Whether new deals land in this pipeline when they are created without a pipeline_id.
currencystringNullable
The pipeline’s own currency (ISO 4217), when one is set.
stagesobject[]
The stages, in board order.
- iduuid
  Stage ID — the value of a deal’s stage_id.
- namestring
  Stage name.
- positioninteger
  Order on the board, ascending.
- typeenum
  Whether deals in this stage are still open, or closed as won or lost.
  One ofopenwonlost
- probabilityintegerNullable
  Default win probability for deals in this stage, in percent.
- colorstring
  Stage colour as a hex code.

The pipeline object

{
  "id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
  "name": "New business",
  "is_default": true,
  "currency": null,
  "stages": [
    {
      "id": "4e8a1c6d-9b2f-4d7a-8c3e-1f5b7a9d0c62",
      "name": "Qualification",
      "position": 0,
      "type": "open",
      "probability": 20,
      "color": "#94a3b8"
    },
    {
      "id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
      "name": "Proposal",
      "position": 1,
      "type": "open",
      "probability": 60,
      "color": "#64748b"
    },
    {
      "id": "7c3f5a9e-4d1b-4e8c-a2f6-9b0d3e5a7c18",
      "name": "Negotiation",
      "position": 2,
      "type": "open",
      "probability": 80,
      "color": "#475569"
    },
    {
      "id": "8a6d2e4f-7c9b-4a1e-b3d5-0f2c4e6a8b39",
      "name": "Won",
      "position": 3,
      "type": "won",
      "probability": 100,
      "color": "#16a34a"
    },
    {
      "id": "1d9f3b5a-6e2c-4f8d-9a7b-3c5e7f9a1b04",
      "name": "Lost",
      "position": 4,
      "type": "lost",
      "probability": 0,
      "color": "#9ca3af"
    }
  ]
}

Find a stage ID

Stage IDs do not change when a stage is renamed or reordered, so look them up once and keep them in your configuration. This finds the default pipeline and its Proposal stage:

stage-id.mjs

const response = await fetch('https://acme.nextora.co/api/v1/pipelines', {
  headers: { Authorization: `Bearer ${process.env.NEXTORA_API_KEY}` },
});
const { data: pipelines } = await response.json();

const pipeline = pipelines.find(item => item.is_default);
const stage = pipeline.stages.find(item => item.name === 'Proposal');
console.log(pipeline.id, stage.id);

List pipelines

GET/api/v1/pipelines

Requires deals:read

Returns every deal pipeline with its stages.

Query parameters

limitinteger
Page size, from 1 to 100.
Default50
cursorstring
The meta.next_cursor of the previous page.

Returns

A list of pipeline objects.

GET/api/v1/pipelines

curl https://acme.nextora.co/api/v1/pipelines \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": [
    {
      "id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
      "name": "New business",
      "is_default": true,
      "currency": null,
      "stages": [
        {
          "id": "4e8a1c6d-9b2f-4d7a-8c3e-1f5b7a9d0c62",
          "name": "Qualification",
          "position": 0,
          "type": "open",
          "probability": 20,
          "color": "#94a3b8"
        },
        {
          "id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
          "name": "Proposal",
          "position": 1,
          "type": "open",
          "probability": 60,
          "color": "#64748b"
        },
        {
          "id": "7c3f5a9e-4d1b-4e8c-a2f6-9b0d3e5a7c18",
          "name": "Negotiation",
          "position": 2,
          "type": "open",
          "probability": 80,
          "color": "#475569"
        },
        {
          "id": "8a6d2e4f-7c9b-4a1e-b3d5-0f2c4e6a8b39",
          "name": "Won",
          "position": 3,
          "type": "won",
          "probability": 100,
          "color": "#16a34a"
        },
        {
          "id": "1d9f3b5a-6e2c-4f8d-9a7b-3c5e7f9a1b04",
          "name": "Lost",
          "position": 4,
          "type": "lost",
          "probability": 0,
          "color": "#9ca3af"
        }
      ]
    },
    {
      "id": "6e0a2c4f-8b1d-4e3a-9c5f-7d9b1e3a5c27",
      "name": "Renewals",
      "is_default": false,
      "currency": "EUR",
      "stages": [
        {
          "id": "2c4e6a8b-0d1f-4a3c-8e5b-7f9a1c3e5d72",
          "name": "Up for renewal",
          "position": 0,
          "type": "open",
          "probability": 70,
          "color": "#94a3b8"
        },
        {
          "id": "9a1c3e5f-7b9d-4f1a-8c3e-5b7d9f1a3c84",
          "name": "Renewed",
          "position": 1,
          "type": "won",
          "probability": 100,
          "color": "#16a34a"
        },
        {
          "id": "4f6b8d0a-2c4e-4a6c-9e8f-1b3d5f7a9c96",
          "name": "Churned",
          "position": 2,
          "type": "lost",
          "probability": 0,
          "color": "#9ca3af"
        }
      ]
    }
  ],
  "meta": {
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}

Retrieve a pipeline

GET/api/v1/pipelines/{id}

Requires deals:read

Returns one pipeline and its stages.

Path parameters

iduuidRequired
The pipeline’s ID.

Returns

The pipeline. 404 not_found when it does not exist.

GET/api/v1/pipelines/{id}

curl https://acme.nextora.co/api/v1/pipelines/9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34 \
  -H "Authorization: Bearer $NEXTORA_API_KEY"

Response200 OK

{
  "data": {
    "id": "9d4b2f7a-3c8e-4b1d-a6f2-5e7c9b0d1a34",
    "name": "New business",
    "is_default": true,
    "currency": null,
    "stages": [
      {
        "id": "4e8a1c6d-9b2f-4d7a-8c3e-1f5b7a9d0c62",
        "name": "Qualification",
        "position": 0,
        "type": "open",
        "probability": 20,
        "color": "#94a3b8"
      },
      {
        "id": "5b1e9f3c-2a7d-4c6e-8f1b-3d9a0c4e7b21",
        "name": "Proposal",
        "position": 1,
        "type": "open",
        "probability": 60,
        "color": "#64748b"
      },
      {
        "id": "7c3f5a9e-4d1b-4e8c-a2f6-9b0d3e5a7c18",
        "name": "Negotiation",
        "position": 2,
        "type": "open",
        "probability": 80,
        "color": "#475569"
      },
      {
        "id": "8a6d2e4f-7c9b-4a1e-b3d5-0f2c4e6a8b39",
        "name": "Won",
        "position": 3,
        "type": "won",
        "probability": 100,
        "color": "#16a34a"
      },
      {
        "id": "1d9f3b5a-6e2c-4f8d-9a7b-3c5e7f9a1b04",
        "name": "Lost",
        "position": 4,
        "type": "lost",
        "probability": 0,
        "color": "#9ca3af"
      }
    ]
  }
}