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.
Two read endpoints are available: list all statuses, and list the active reasons configured on a status. There is no pagination or filtering — 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 or PATCH /api/external/appointments/:id/outcome.
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.
call_categories	string[] (enum)	Call categories this status may be used on when logging an appointment outcome. Appointment outcomes are rejected when the appointment call category is not listed here. See Call Category Values.
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",
      "call_categories": ["SALES_CALL", "COACHING_CALL", "TRIAGE_CALL"],
      "text_color": "#1E40AF",
      "bg_color": "#DBEAFE"
    },
    {
      "id": "status_002def",
      "name": "Closed Won",
      "role": "WON",
      "type": "BOTH",
      "description": "Deal successfully closed",
      "call_categories": ["SALES_CALL"],
      "text_color": "#14532D",
      "bg_color": "#DCFCE7"
    },
    {
      "id": "status_003ghi",
      "name": "No Show",
      "role": "NO_SHOW",
      "type": "APPOINTMENT",
      "description": null,
      "call_categories": ["SALES_CALL", "COACHING_CALL", "TRIAGE_CALL"],
      "text_color": "#7C3AED",
      "bg_color": "#EDE9FE"
    }
  ]
}

List Status Reasons

Reasons are the configurable loss/disqualification reasons an organization defines on a status. They only exist on statuses with role LOST or UNQUALIFIED; for any other status this endpoint returns an empty list. Use it to look up the reason_id (or exact reason name) to send when logging an outcome via PATCH /api/external/appointments/:id/outcome or a lead status via PATCH /api/external/leads/:id/status. Only active reasons are returned — archived reasons are omitted because they can no longer be selected.

Returns the active reasons configured on a status, ordered by their configured position.

GET/api/external/statuses/:id/reasons

Reason Object Fields

Field	Type	Description
id	string (UUID)	Unique identifier of the reason. Send this as reason_id when logging a status/outcome.
name	string	Display name of the reason. Can be sent as reason_name instead of the id.
position	number	Display order configured by the organization (ascending).

Code Examples

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

Response Example

json

{
  "success": true,
  "message": "Status reasons fetched successfully",
  "data": [
    {
      "id": "reason_001abc",
      "name": "Too expensive",
      "position": 0
    },
    {
      "id": "reason_002def",
      "name": "Bad timing",
      "position": 1
    },
    {
      "id": "reason_003ghi",
      "name": "Went with a competitor",
      "position": 2
    }
  ]
}

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

Call Category Values

Value	Description
SALES_CALL	Sales call
COACHING_CALL	Coaching call
TRIAGE_CALL	Triage call

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": "Rate limit exceeded for this organization. Retry after the number of seconds in the Retry-After header."
}