Statuses API Reference

Retrieve every sales status defined in your organization.

Overview:This endpoint returns every sales status defined in your organization. It is primarily used to **look up status IDs** before calling write endpoints that require one — for example, updating a lead's status via PATCH /api/external/leads/:id/status.
There is a single endpoint: list all statuses. There is no pagination, no filtering, and no detail/by-ID endpoint — the full set is always returned, ordered alphabetically by name.

List Statuses

Returns all sales statuses for your organization, ordered alphabetically by name. No pagination — the full set is always returned in a single call.

GET/api/external/statuses

Status Object Fields

Field	Type	Description
id	string (UUID)	Unique identifier. Use this id when calling PATCH /api/external/leads/:id/status.
name	string	Display name of the status.
role	string (enum)	The functional role this status represents. See Role Values.
type	string (enum)	Which entity boards this status appears on. See Type Values.
description	string \| null	Optional description. null when not set.
text_color	string	Hex color code for the status label text (e.g. "#14532D").
bg_color	string	Hex color code for the status label background (e.g. "#DCFCE7").

Code Examples

curl -X GET "https://api.hermon.io/api/external/statuses" \
  -H "x-api-key: sk_live_your_key_here"

Response Example

json

{
  "success": true,
  "message": "Statuses fetched successfully",
  "data": [
    {
      "id": "status_001abc",
      "name": "Appointment Booked",
      "role": "APPOINTMENT_BOOKED",
      "type": "BOTH",
      "description": "Lead has a scheduled appointment",
      "text_color": "#1E40AF",
      "bg_color": "#DBEAFE"
    },
    {
      "id": "status_002def",
      "name": "Closed Won",
      "role": "WON",
      "type": "BOTH",
      "description": "Deal successfully closed",
      "text_color": "#14532D",
      "bg_color": "#DCFCE7"
    },
    {
      "id": "status_003ghi",
      "name": "No Show",
      "role": "NO_SHOW",
      "type": "APPOINTMENT",
      "description": null,
      "text_color": "#7C3AED",
      "bg_color": "#EDE9FE"
    }
  ]
}

Values Reference

Role Values

Value	Description
NEW_LEAD	New/unqualified lead
APPOINTMENT_BOOKED	Appointment scheduled
NO_SHOW	Lead did not attend the appointment
RESCHEDULED	Appointment rescheduled
CANCELED	Appointment canceled
PARTIAL_PAYMENT	Partial payment received
WON	Deal won/closed
UNQUALIFIED	Lead disqualified
FOLLOW_UP	Requires follow-up
LOST	Deal lost

Type Values

Value	Description
LEAD	Visible on the Lead board only
APPOINTMENT	Visible on the Appointment board only
BOTH	Visible on both Lead and Appointment boards

Usage Pattern

Typical Use Case: The typical use case for this endpoint is a two-step flow:

Fetch all statuses to find the id of the status you want to apply.
Update the lead using that id on the Lead Status Update endpoint.

Error Responses

401Missing or invalid API key

json

{
  "status": "error",
  "message": "Invalid or revoked API key"
}

404Resource not found

json

{
  "status": "error",
  "message": "Resource not found"
}

429Rate limit exceeded

json

{
  "status": "error",
  "message": "Too many requests"
}