> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Statuses

> The Custom Statuses API lets you define the custom session statuses your team works with, and read or set the custom status on any session.

Every session has one of three built-in statuses: `open`, `closed_resolved`, or `closed_unresolved`. A custom status refines one of them with a name your team recognizes, such as "Waiting on customer" or "Escalated to engineering", plus an optional customer-facing label, color, and icon. This API manages those definitions and reads or sets the custom status on a session.

## Key Concepts

* **Custom status** — A named refinement of a built-in status. Each one has a `parent_status`; applying it to a session moves the session to that built-in status
* **`sub_status_id`** — Every session object carries the id of its custom status, or `null` when only the built-in status applies. Resolve ids with the list endpoint
* **Applying and clearing** — Set a session's custom status with `PUT /chat/sessions/{session_id}/sub-status`; clear it with `DELETE` on the same path. Clearing keeps the built-in status exactly as it is
* **Filtering** — `POST /chat/sessions/filter` accepts `sub_status_ids` to find sessions in any of the given custom statuses
* **Team access** — `allowed_group_ids` lists the teams whose agents may set the status from the inbox. An empty list allows every team. Deleting a team removes it from every list, so a status whose only allowed team is deleted becomes available to every team. Admins, API keys, and workflows can always set it, and a status already on a session stays visible to everyone
* **Customer-facing fields** — `display_name` and `display_description` are what customers may see; `name` and `description` are for your team only
* **Timeline** — Every set and clear leaves an event in the session history, attributed to the API

## Available Endpoints

<CardGroup>
  <Card title="List Custom Statuses" icon="list" href="./list">
    List every custom status in your organization
  </Card>

  <Card title="Get Custom Status" icon="eye" href="./get">
    Fetch one custom status by id
  </Card>

  <Card title="Create Custom Status" icon="plus" href="./create">
    Define a new custom status under a built-in one
  </Card>

  <Card title="Update Custom Status" icon="pen" href="./update">
    Change any subset of a custom status
  </Card>

  <Card title="Delete Custom Status" icon="trash" href="./delete">
    Remove a custom status
  </Card>

  <Card title="Set Session Custom Status" icon="circle-check" href="../chat-sessions/sub_status_set">
    Apply a custom status to a session
  </Card>

  <Card title="Clear Session Custom Status" icon="circle-xmark" href="../chat-sessions/sub_status_clear">
    Remove the custom status from a session
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.