List Lead Status Definitions¶

Your organisation's status catalogue, with the reasons and sub-reasons each status accepts.

Endpoint¶

GET /v2/lead-status-definitions

Request¶

curl --location '{base_url}/v2/lead-status-definitions' \
  --header 'Authorization: Bearer JWT_TOKEN'

Response¶

Success Response¶

Code: 200 OK

{
  "items": [
    {
      "id": "8d2c5e0a-41f7-4b3e-9a6d-2f1b7c4e9a01",
      "label": "New Lead",
      "stage": "NEW",
      "is_system": true,
      "sort_order": 0,
      "reasons": []
    },
    {
      "id": "c4a91f37-0b6e-4d28-8f15-6e3a2b9d7c42",
      "label": "Contacted",
      "stage": "IN_PROGRESS",
      "is_system": false,
      "sort_order": 1,
      "reasons": [
        {
          "id": "1f6b8d24-93ce-4a57-b0e1-5c7d2a9f3e18",
          "label": "Left voicemail",
          "needs_follow_up": true,
          "sort_order": 0,
          "subreasons": []
        },
        {
          "id": "5e9a2c71-d84b-4f06-a3c9-0b7e1f6d2a55",
          "label": "Spoke with patient",
          "needs_follow_up": false,
          "sort_order": 1,
          "subreasons": [
            {
              "id": "a7d3f5b9-2c18-4e6a-9b40-8f1c5e2d7b63",
              "label": "Interested, deciding",
              "sort_order": 0
            },
            {
              "id": "3b8e6a1d-f9c2-47d5-8e03-a6c4b2f1d970",
              "label": "Has questions",
              "sort_order": 1
            }
          ]
        }
      ]
    },
    {
      "id": "d4a8e1c6-7f2b-4e93-8c5a-0b6d3f9e2a71",
      "label": "Converted",
      "stage": "CONVERTED",
      "is_system": true,
      "sort_order": 98,
      "reasons": []
    },
    {
      "id": "e2f7c9a4-6b1d-4c83-b5e9-1d0a7f3c8b26",
      "label": "Dropped",
      "stage": "DROPPED",
      "is_system": true,
      "sort_order": 99,
      "reasons": [
        {
          "id": "6c2e9f41-8b5d-4a7c-9e13-2d4f7a8b1c95",
          "label": "Out of area",
          "needs_follow_up": false,
          "sort_order": 0,
          "subreasons": [
            {
              "id": "b9d14e72-3c6a-4f85-a0b2-7e5c1d9f4a36",
              "label": "Moved away",
              "sort_order": 0
            }
          ]
        }
      ]
    }
  ]
}

Response Fields¶

Field	Type	Description
`items`	array of object	Every status in your organisation's catalogue. See Items.

Items¶

Field	Type	Description
`id`	string	The id to send as `status_id`, `reason_id` or `subreason_id`. It stays the same when the name changes.
`label`	string	Display label, as your organisation configured it.
`stage`	string	The stage this status belongs to. Choosing an `IN_PROGRESS` status moves a `NEW` lead to `IN_PROGRESS`; nothing moves a lead back, so a lead's own stage can be ahead of its status's. The `CONVERTED` stage holds only the system Converted status, which a booked appointment sets. One of `NEW`, `IN_PROGRESS`, `CONVERTED`, `DROPPED`.
`is_system`	boolean	System statuses can't be removed by the organisation. There are three: the `NEW`-stage one a lead is raised on, the `CONVERTED`-stage one a booked appointment puts it on (it can't be changed at all), and the `DROPPED`-stage one a drop puts it on.
`sort_order`	integer	Display order within its list.
`reasons`	array of object	The reasons a change to this status can cite. See Reasons.

Reasons¶

Field	Type	Description
`id`	string	The id to send as `status_id`, `reason_id` or `subreason_id`. It stays the same when the name changes.
`label`	string	Display label, as your organisation configured it.
`needs_follow_up`	boolean	When true, a status change citing this reason must carry `follow_up_date`.
`sort_order`	integer	Display order within its list.
`subreasons`	array of object	Finer reasons under this one. See Subreasons.

Subreasons¶

Field	Type	Description
`id`	string	The id to send as `status_id`, `reason_id` or `subreason_id`. It stays the same when the name changes.
`label`	string	Display label, as your organisation configured it.
`sort_order`	integer	Display order within its list.

Error Response¶

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	`code`	Meaning
`400 Bad Request`	`bad_request`	The request body or parameters failed validation. `errors[]` names the offending fields.
`401 Unauthorized`	`unauthorized`	The access token is missing, malformed or expired.
`403 Forbidden`	`forbidden`	The request references a resource outside the token's organisation or clinic scope.
`404 Not Found`	`not_found`	No such resource, or it's outside your scope.
`429 Too Many Requests`	`rate_limited`	Rate limit exceeded. Back off and retry.
`500 Internal Server Error`	`internal_error`	Unexpected server error.
`502 Bad Gateway`	`upstream_error`	Upstream service failed or timed out.

Notes¶

Statuses are defined per organisation and named by id, which stays the same when a status is renamed — read this list rather than hard-coding a set. Every organisation has three system statuses: the NEW-stage one a lead is raised on, the CONVERTED-stage one a booked appointment puts it on, and the DROPPED-stage one a drop puts it on. Your own statuses are all IN_PROGRESS.
The CONVERTED-stage status has no reasons and can't be chosen or changed — booking an appointment against the lead's case is what puts a lead on it.
A reason marked needs_follow_up makes follow_up_date mandatory on a status change that cites it.
A status your organisation removes leaves this list, but leads that already have it keep its id and name. It can no longer be chosen.