Statuses

Statuses in BenchKey are tenant-configurable, every shop can rename, add, and re-order its workflow. These read-only discovery endpoints return the exact values the rest of the API accepts, so your integration never has to hardcode or guess status strings:

• Ticket statuses: the values accepted by POST /tickets/:id/status
• Queues: valid targets for queue assignment (e.g. queue_name on ticket create)
• Lead statuses: the machine keys accepted by the lead endpoints

All three are settings-style lists: small, returned in full, not paginated.

---

List ticket statuses

GET /api/v1/statuses

Returns the tenant’s configured ticket status catalog, in display order, the exact values accepted by POST /tickets/:id/status. Statuses with is_system: true are set by business logic and cannot be renamed or deleted. Tenants that have never customized statuses get the standard default catalog.

Scope required: tickets.read

curl

curl "https://app.benchkey.com/api/v1/statuses" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

const res = await fetch("https://app.benchkey.com/api/v1/statuses", {
  headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" },
});
const { data } = await res.json();
const validStatuses = data.map((s) => s.name);

Response

{
  "object": "list",
  "data": [
    {
      "object": "ticket_status",
      "name": "Waiting for Parts",
      "color_category": "warning",
      "is_system": false
    },
    {
      "object": "ticket_status",
      "name": "Ready for Pickup",
      "color_category": "success",
      "is_system": true
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Field	Type	Description
name	string	The exact status string ticket endpoints accept
color_category	string	Display color bucket: accent, neutral, success, warning, or danger
is_system	boolean	Set by business logic; cannot be renamed or deleted

---

List queues

GET /api/v1/statuses/queues

Returns the tenant’s queue list in display order, valid targets for queue assignment. id and color are null for legacy tenants whose queues predate the queues table.

Scope required: tickets.read

curl

curl "https://app.benchkey.com/api/v1/statuses/queues" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Response

{
  "object": "list",
  "data": [
    {
      "object": "queue",
      "id": 1,
      "name": "Front Bench",
      "color": "#539bf5",
      "display_order": 0
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Field	Type	Description
id	integer|null	Queue ID (null for legacy tenants whose queues predate the queues table)
name	string	Queue name, the value queue_name fields accept
color	string|null	Display color
display_order	integer	Position in the app’s queue list

---

List lead statuses

GET /api/v1/statuses/leads

Returns the tenant’s lead status registry in pipeline order. key is the machine value lead endpoints accept; is_terminal marks end states (won/lost) excluded from auto-chain progression; follow_up_after_days is the auto-advance timer (null = none).

Scope required: leads.read

curl

curl "https://app.benchkey.com/api/v1/statuses/leads" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Response

{
  "object": "list",
  "data": [
    {
      "object": "lead_status",
      "key": "new",
      "label": "New",
      "color": "#539bf5",
      "order_index": 0,
      "follow_up_after_days": 2,
      "is_terminal": false,
      "is_system": true
    },
    {
      "object": "lead_status",
      "key": "won",
      "label": "Won",
      "color": "#57ab5a",
      "order_index": 5,
      "follow_up_after_days": null,
      "is_terminal": true,
      "is_system": true
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Field	Type	Description
key	string	Machine key lead endpoints accept (e.g. "new", "pending")
label	string	Human display label
color	string|null	Display color
order_index	integer	Pipeline display order
follow_up_after_days	integer|null	Auto-advance timer in days (null = no timer)
is_terminal	boolean	End state (won/lost); excluded from auto-chain progression
is_system	boolean	Seeded system status; protected from deletion

---

Error codes

HTTP status	Code	Meaning
401	unauthorized	Key is missing, malformed, or revoked
403	insufficient_scope	API key lacks tickets.read (ticket statuses, queues) or leads.read (lead statuses)

See Errors for the full error envelope format.