Skip to main content
POST
Create a custom status

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
name
string
required

Internal name shown to agents in the inbox (unique per organization, 1-100 chars)

Required string length: 1 - 100
parent_status
enum<string>
required

Built-in status this custom status refines: "open", "closed_resolved", or "closed_unresolved". Applying the custom status to a session moves the session to this built-in status, so an "open"-parented status reopens a closed session and a "closed_*"-parented one closes it.

Available options:
closed_resolved,
closed_unresolved,
open
description
string

Internal note for agents on when to use this status. Never shown to customers.

display_name
string

Customer-facing label (max 100 chars). Falls back to name when omitted.

Maximum string length: 100
display_description
string

Customer-facing explanation. No fallback: when omitted, customers see no description.

color
string

Badge color as #RRGGBB. Omit to inherit the parent status color.

Pattern: ^#[0-9a-fA-F]{6}$
icon
string

Inline SVG markup for the badge icon (sanitized server-side, max 10,000 chars). Omit for the default icon.

Maximum string length: 10000
Pattern: ^<svg[\s>]

Response

Default Response

id
string
required
org_id
string
required
name
string
required
description
string | null
required
display_name
string | null
required
display_description
string | null
required
color
string | null
required
icon
string | null
required
parent_status
enum<string>
required
Available options:
closed_resolved,
closed_unresolved,
open
created_at
string<date-time>
required
updated_at
string<date-time>
required