Update sub-status
/v1/sub-statuses/{id}org.permission.sub_status.updateThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Updates an existing sub-status.
Sub-statuses
A sub-status adds detail inside one of the three main statuses, open, snoozed or done, such as "Waiting on warehouse" under snoozed or "Resolved by refund" under done. Admins define them, and agents pick one when they change a conversation's or custom object's status.
Every conversation, and every custom object (KObject), has a status of open, snoozed or done. Those three values drive Kustomer's behavior: what appears in queues and searches, when snoozes wake up, and when SLAs and CSAT surveys run. They can't be renamed or extended. Sub-statuses are how an org adds its own vocabulary on top without changing that behavior. Each sub-status belongs to exactly one parent status, and the record stores the chosen sub-status ID in its subStatus attribute. Agents choose sub-statuses from the status menu in the agent desktop, and you can search conversations by them with the conversation_sub_status attribute.
Key fields
| Field | Meaning |
|---|---|
label |
The name agents see. |
description |
What the sub-status is for. Required when you create one. |
parentStatus |
open, snoozed or done. |
resourceType |
conversation or kobject. Can't be changed after creation. |
default |
Whether this is the sub-status applied automatically for its parent status. |
Sub-statuses for custom objects belong to one Klass. When you create one with resourceType: "kobject", also send parentId (the Klass ID) or parentName (the Klass name), and filter lists the same way.
Defaults and status changes
Each parent status has at most one default sub-status per resource type (per Klass for custom objects). The first sub-status you create for a parent status becomes its default automatically, and setting default: true on another one moves the default to it.
When a conversation's status changes and the request doesn't include a subStatus, Kustomer sets the default sub-status for the new status, or clears it if there's no default. If you do send a subStatus, it must be an existing sub-status ID, and on a PUT it must also belong to the conversation's new status, or the update fails with 404. Send subStatus: null to clear it.
Which endpoint to use
| To | Call |
|---|---|
| List the sub-statuses agents can choose | GET /v1/sub-statuses, with resource (required) and optionally parentId or parentName |
Look up one or more sub-statuses by ID, for example to show a conversation's subStatus label |
GET /v1/sub-statuses/{id}, with comma-separated IDs for several |
| Create a sub-status | POST /v1/sub-statuses |
| Rename, redescribe or make one the default | PUT /v1/sub-statuses/{id} |
| Retire a sub-status | DELETE /v1/sub-statuses/{id} |
Deleting is a soft delete: the response returns the sub-status with its deletion recorded, and records that already use it keep the ID in subStatus. Reading sub-statuses requires read access to the matching resource type, conversations or custom objects, and writing them requires admin permission.
Path parameters
Resource ID.
"60254e3ec413ae00571e3c96"Request body
application/jsonrequiredDisplay name for the sub-status
"Waiting for Customer"Description of the sub-status
"Conversation is waiting for customer response"Whether this is the default sub-status for the parent status
falseResponses
OK