Custom Ticket Statuses indicate the state of a ticket. Each custom ticket status must belong to a status category.

Custom Ticket Statuses and Status Categories

Each custom ticket status must belong to one of five ticket status categories. The status categories consist of the existing five legacy ticket statuses:

  • New
  • Open
  • Pending
  • On-hold
  • Solved

In the case of tickets with the legacy Closed status, Zendesk automation will use a custom ticket status belonging to the Solved status category.

Each status category has one default custom ticket status which must always be Active. The only exception is the On-hold category when the category is disabled. The New status category has only one custom ticket status and is the default. The New category's one and only custom ticket status can never be deactivated.

Changing a custom ticket status from default to non-default is not allowed. The only way to change the default custom ticket status is by using the Bulk Update Default Custom Ticket Status API.

Custom Ticket Status limits

There are limits for creating custom ticket status.

  • 300 custom ticket status per account
  • 100 custom ticket status per status category

JSON format

Custom Ticket Statuses are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
active boolean false false If true, the custom status is set to active, If false, the custom status is set to inactive
agent_label string false true The label displayed to agents. Maximum length is 48 characters
created_at string true false The date and time the custom ticket status was created
default boolean false false If true, the custom status is set to default. If false, the custom status is set to non-default
description string false false The description of when the user should select this custom ticket status
end_user_description string false false The description displayed to end users
end_user_label string false false The label displayed to end users. Maximum length is 48 characters
id integer true false Automatically assigned when the custom ticket status is created
raw_agent_label string true false The dynamic content placeholder. If the dynamic content placeholder is not available, this is the "agent_label" value. See Dynamic Content Items
raw_description string true false The dynamic content placeholder. If the dynamic content placeholder is not available, this is the "description" value. Dynamic Content Items
raw_end_user_description string true false The dynamic content placeholder. If the dynamic content placeholder is not available, this is the "end_user_description" value. See Dynamic Content Items
raw_end_user_label string true false The dynamic content placeholder. If the dynamic content placeholder is not available, this is the "end_user_label" value. See Dynamic Content Items
status_category string false true The status category the custom ticket status belongs to. Allowed values are "new", "open", "pending", "hold", or "solved".
updated_at string true false The date and time the custom ticket status was last updated

List Custom Ticket Statuses

  • GET /api/v2/custom_statuses

Lists all undeleted custom ticket statuses for the account. No pagination is provided.

You can't have more than 300 custom ticket statuses at a time.

Allowed For

  • End Users

Parameters

Name Type In Required Description
active boolean Query false If true, show only active custom ticket statuses. If false, show only inactive custom ticket statuses. If the filter is not used, show all custom ticket statuses
default boolean Query false If true, show only default custom ticket statuses. If false, show only non-default custom ticket statuses. If the filter is not used, show all custom ticket statuses
status_categories string Query false Filter the list of custom ticket statuses by a comma-separated list of status categories
curl
curl https://{subdomain}.zendesk.com/api/v2/custom_statuses.json \  -v -u {email_address}:{password}

Example response(s)

200 OK
// Status 200 OK
{  "custom_statuses": [    {      "active": true,      "agent_label": "Responding quickly",      "created_at": "2021-07-20T22:55:29Z",      "default": false,      "description": "Customer needs a response quickly",      "end_user_description": "Your ticket is being responded to",      "end_user_label": "Urgent processing",      "id": 35436,      "raw_agent_label": "Responding quickly",      "raw_description": "Customer needs a response quickly",      "raw_end_user_description": "Your ticket is being responded to",      "raw_end_user_label": "Urgent processing",      "status_category": "open",      "updated_at": "2021-07-20T22:55:29Z"    }  ]}

Show Custom Ticket Status

  • GET /api/v2/custom_statuses/{custom_status_id}

Returns the custom ticket status object.

Allowed For

  • End Users

Parameters

Name Type In Required Description
custom_status_id integer Path true The id of the custom status
curl
curl https://{subdomain}.zendesk.com/api/v2/custom_status/{custom_status_id}.json \  -v -u {email_address}:{password}

Example response(s)

200 OK
// Status 200 OK
{  "custom_status": {    "active": true,    "agent_label": "Responding quickly",    "created_at": "2021-07-20T22:55:29Z",    "default": false,    "description": "Customer needs a response quickly",    "end_user_description": "Your ticket is being responded to",    "end_user_label": "Urgent processing",    "id": 35436,    "raw_agent_label": "Responding quickly",    "raw_description": "Customer needs a response quickly",    "raw_end_user_description": "Your ticket is being responded to",    "raw_end_user_label": "Urgent processing",    "status_category": "open",    "updated_at": "2021-07-20T22:55:29Z"  }}

Create Custom Ticket Status

  • POST /api/v2/custom_statuses

Takes a custom_status object that specifies the custom ticket status properties to create.

Allowed For

  • Admins

Request body format

Name Type Mandatory Description
active boolean false If true, the custom status is set to active. If false, the custom status is set to inactive
agent_label string true The dynamic content placeholder or the label displayed to agents. Maximum length for displayed label is 48 characters
description string false The description of when the user should select this custom ticket status
end_user_description false false The description displayed to end users
end_user_label string false The dynamic content placeholder or the label displayed to end users. Maximum length for displayed label is 48 characters
status_category string true The status category the custom status belongs to. Allowed values are "new", "open", "pending", "hold", or "solved"

Example body

{  "custom_status": {    "active": true,    "agent_label": "Responding quickly",    "description": "Customer needs a response quickly",    "end_user_description": "Your ticket is being responded to",    "end_user_label": "Urgent processing",    "status_category": "open"  }}
curl
curl https://{subdomain}.zendesk.com/api/v2/custom_statuses.json \  -d '{"custom_status": {"status_category": "open", "agent_label": "Responding quickly", "end_user_label": "Urgent processing", "description": "Responding quickly", "end_user_description": "Responding quickly"}}' \  -H "Content-Type: application/json" -v -u {email_address}:{password} -X POST

Example response(s)

201 Created
// Status 201 Created
{  "custom_status": {    "active": true,    "agent_label": "Responding quickly",    "created_at": "2021-07-20T22:55:29Z",    "default": false,    "description": "Customer needs a response quickly",    "end_user_description": "Your ticket is being responded to",    "end_user_label": "Urgent processing",    "id": 35436,    "raw_agent_label": "Responding quickly",    "raw_description": "Customer needs a response quickly",    "raw_end_user_description": "Your ticket is being responded to",    "raw_end_user_label": "Urgent processing",    "status_category": "open",    "updated_at": "2021-07-20T22:55:29Z"  }}

Update Custom Ticket Status

  • PUT /api/v2/custom_statuses/{custom_status_id}

Takes a custom_status object that specifies the properties to update.

Allowed For

  • Admins

Request body format

Name Type Description
active boolean If true, the custom status is set to active. If false, the custom status is set to inactive
agent_label string The dynamic content placeholder or the label displayed to agents. Maximum length for displayed label is 48 characters
description string The description of when the user should select this custom ticket status
end_user_description string The description displayed to end users
end_user_label string The dynamic content placeholder or the label displayed to end users. Maximum length for displayed label is 48 characters

Parameters

Name Type In Required Description
custom_status_id integer Path true The id of the custom status

Example body

{  "custom_status": {    "active": true,    "agent_label": "Responding quickly",    "description": "Customer needs a response quickly",    "end_user_description": "Your ticket is being responded to",    "end_user_label": "Urgent processing"  }}
curl
curl https://{subdomain}.zendesk.com/api/v2/custom_statuses/{custom_status_id}.json \  -d '{"custom_status": {"agent_label": "{{dc.quick}}", "end_user_label": "{{dc.urgent}}"}}' \  -H "Content-Type: application/json" -v -u {email_address}:{password} -X PUT

Example response(s)

200 OK
// Status 200 OK
{  "custom_status": {    "active": true,    "agent_label": "Responding quickly",    "created_at": "2021-07-20T22:55:29Z",    "default": false,    "description": "Customer needs a response quickly",    "end_user_description": "Your ticket is being responded to",    "end_user_label": "Urgent processing",    "id": 35436,    "raw_agent_label": "Responding quickly",    "raw_description": "Customer needs a response quickly",    "raw_end_user_description": "Your ticket is being responded to",    "raw_end_user_label": "Urgent processing",    "status_category": "open",    "updated_at": "2021-07-20T22:55:29Z"  }}

Bulk Update Default Custom Ticket Status

  • PUT /api/v2/custom_status/default

Updates the default values for many custom ticket statuses at once.

Allowed For

  • Admins

Request body format

Name Type Description
ids string The comma-separated list of custom status ids to be set as default for their category

Example body

{  "ids": "1234567,1234577"}
curl
curl https://{subdomain}.zendesk.com/api/v2/custom_status/default.json \  -d '{"ids": "1234567,1234577"}' \  -H "Content-Type: application/json" -v -u {email_address}:{password} -X PUT

Example response(s)

200 OK
// Status 200 OK
{}