Omnichannel Routing Percentage-based Queues API

(Enterprise plans only) Custom queues can be split into up to 5 subqueues to distribute certain percentages of tickets that meet the custom queue's conditions to different primary and secondary groups.

The percentages for subqueues must total 100%.

A parent queue is represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
created_at	string	true	false	The time the queue was created
definition	object	false	true	Conditions when queue could be applied
description	string	false	false	The description of the queue
id	string	true	false	Automatically assigned when creating queue
name	string	false	true	The name of the queue
order	integer	false	false	The queue-applied order
updated_at	string	true	false	The time of the queue's last update
url	string	true	false	The API URL of the queue
subqueues	object	false	true	The list of subqueues

A subqueue is represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
id	string	true	false	Automatically assigned when creating subqueue
name	string	false	true	The name of the subqueue
percentage	integer	false	true	Percentage of tickets assigned to the subqueue. The total percentage must be 100
primary_groups	object	false	true	Primary group ids linked to the subqueue
priority	integer	false	true	The subqueue-applied priority
secondary_groups	object	false	false	Secondary group ids linked to the subqueue

Example

{  "queue": {    "url": "https://{subdomain}.zendesk.com/api/v2/queues/01JS1ER11YFTHV23SNY2NH0FT3.json",    "id": "01JS1ER11YFTHV23SNY2NH0FT3",    "name": "New queue",    "description": "Queue description",    "created_at": "2025-04-17T08:44:46Z",    "updated_at": "2025-04-17T08:44:46Z",    "order": 1,    "definition": {      "all": [        {          "field": "priority",          "operator": "is",          "value": "urgent"        }      ],      "any": [        {          "field": "priority",          "operator": "is",          "value": "normal"        }      ]    },    "subqueues": {      "count": 2,      "subqueues": [        {          "id": "01JS1ER137972A16XTPSNNWRR0",          "name": "Subqueue 1",          "priority": 1,          "percentage": 80,          "primary_groups": {            "count": 1,            "groups": [              {                "id": 5683164526079,                "name": "Support"              }            ]          },          "secondary_groups": {            "count": 0,            "groups": []          }        },        {          "id": "01JS1ER13M9T0YFATJHRYCRTC8",          "name": "Subqueue 2",          "priority": 1,          "percentage": 20,          "primary_groups": {            "count": 1,            "groups": [              {                "id": 5683164615423,                "name": "Group A"              }            ]          },          "secondary_groups": {            "count": 0,            "groups": []          }        }      ]    }  }}

Create Queue with Subqueues

POST /api/v2/queues

Allowed For

Admins

Details

If the rate limit for creating omnichannel routing queues is exceeded, wait 1 minute and try again.

Rate Limits	Scopes	Interval	Sandbox	Trial	Default
Standard		1 minute	N/A	N/A	50

"Default" applies to all Zendesk suite and Support plans. Refer to the general account limits for more information.

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/queues.json \  -H "Content-Type: application/json" \  -d '{ "queue": { "name": "New queue", "description": "Queue description", "definition": {   "all": [  {    "field": "priority",    "operator": "is",    "value": "urgent"  }   ],   "any": [  {    "field": "priority",    "operator": "is",    "value": "normal"  }   ] }, "subqueues": [ { "name": "New subqueue", "priority": 1, "percentage": "100", "primary_groups_id": [1100002759994], "secondary_groups_id": [4398063790591] } ] }}' \  -v -u {email_address}/token:{api_token} -X POST

import (  "fmt"  "io"  "net/http")
func main() {  url := "https://example.zendesk.com/api/v2/queues"  method := "POST"  req, err := http.NewRequest(method, url, nil)
  if err != nil {    fmt.Println(err)    return  }  req.Header.Add("Content-Type", "application/json")  req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
  client := &http.Client {}  res, err := client.Do(req)  if err != nil {    fmt.Println(err)    return  }  defer res.Body.Close()
  body, err := io.ReadAll(res.Body)  if err != nil {    fmt.Println(err)    return  }  fmt.Println(string(body))}

Java

import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/queues")    .newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),    """""");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()    .url(urlBuilder.build())    .method("POST", body)    .addHeader("Content-Type", "application/json")    .addHeader("Authorization", basicAuth)    .build();Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var config = {  method: 'POST',  url: 'https://example.zendesk.com/api/v2/queues',  headers: {  'Content-Type': 'application/json',  'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});

Python

import requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/queues"headers = {  "Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(  "POST",  url,  auth=auth,  headers=headers)
print(response.text)

Ruby

require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/queues")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|  http.request(request)end

Example response(s)

201 Created

// Status 201 Created
{  "queue": {    "url": "https://{subdomain}.zendesk.com/api/v2/queues/01JRDA4FMYF636GG27TVR6HBZ5.json",    "id": "01JRDA4FMYF636GG27TVR6HBZ5",    "name": "New queue",    "description": "Queue description",    "created_at": "2025-04-09T12:59:22Z",    "updated_at": "2025-04-09T12:59:22Z",    "order": 1,    "definition": {      "all": [        {          "field": "priority",          "operator": "is",          "value": "urgent"        }      ],      "any": [        {          "field": "priority",          "operator": "is",          "value": "normal"        }      ]    },    "subqueues": {      "count": 1,      "subqueues": [        {          "id": "01JRDA4FPVQGHKBNZ53F3ZG52K",          "name": "New subqueue",          "priority": 1,          "percentage": 100,          "primary_groups": {            "count": 1,            "groups": [              {                "id": 1100002759994,                "name": "g1"              }            ]          },          "secondary_groups": {            "count": 1,            "groups": [              {                "id": 4398063790591,                "name": "g2"              }            ]          }        }      ]    }  }}

Update Queue or Subqueues

PUT /api/v2/queues/{queue_id}

Updates the queue or subqueues of a specified queue.

You can add or delete subqueues by adding or removing them from the subqueues object. The percentage values of the subqueues should total 100 after making the change. For more information, see Subqueues.

You can update the attributes of a subqueue by including the id in the subqueues object.

If you omit the subqueues object, all existing subqueues will be deleted.

Admins

Parameters

Name	Type	In	Required	Description
queue_id	string	Path	true	The id of the omnichannel routing queue

Details

If the rate limit for updating omnichannel routing queues is exceeded, wait 1 minute and try again.

Rate Limits	Scopes	Interval	Sandbox	Trial	Default
Standard		1 minute	N/A	N/A	50

"Default" applies to all Zendesk suite and Support plans. Refer to the general account limits for more information.

Code Samples

curl

curl -X PUT https://{subdomain}.zendesk.com/api/v2/queues/{queue_id}.json \  -H "Content-Type: application/json" \  -d '{ "queue": { "name": "New queue 2", "description": "Queue description 2", "priority": 10, "definition": {   "all": [  {    "field": "priority",    "operator": "is",    "value": "urgent"  }   ],   "any": [  {    "field": "priority",    "operator": "is",    "value": "normal"  }   ] }, "primary_groups_id": [1100002759994], "secondary_groups_id": [4398063790591] }}' \  -v -u {email_address}/token:{api_token}

import (  "fmt"  "io"  "net/http")
func main() {  url := "https://example.zendesk.com/api/v2/queues/01HG80ATNNZK1N7XRFVKX48XD6"  method := "PUT"  req, err := http.NewRequest(method, url, nil)
  if err != nil {    fmt.Println(err)    return  }  req.Header.Add("Content-Type", "application/json")  req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
  client := &http.Client {}  res, err := client.Do(req)  if err != nil {    fmt.Println(err)    return  }  defer res.Body.Close()
  body, err := io.ReadAll(res.Body)  if err != nil {    fmt.Println(err)    return  }  fmt.Println(string(body))}

Java

import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/queues/01HG80ATNNZK1N7XRFVKX48XD6")    .newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),    """""");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()    .url(urlBuilder.build())    .method("PUT", body)    .addHeader("Content-Type", "application/json")    .addHeader("Authorization", basicAuth)    .build();Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');
var config = {  method: 'PUT',  url: 'https://example.zendesk.com/api/v2/queues/01HG80ATNNZK1N7XRFVKX48XD6',  headers: {  'Content-Type': 'application/json',  'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});

Python

import requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/queues/01HG80ATNNZK1N7XRFVKX48XD6"headers = {  "Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(  "PUT",  url,  auth=auth,  headers=headers)
print(response.text)

Ruby

require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/queues/01HG80ATNNZK1N7XRFVKX48XD6")request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|  http.request(request)end

Example response(s)

200 OK

// Status 200 OK
{  "queue": {    "created_at": "2023-09-27T09:06:34Z",    "definition": {      "all": [        {          "field": "priority",          "operator": "is",          "value": "urgent"        }      ],      "any": []    },    "description": "Queue description 2",    "id": "01HG80ATNNZK1N7XRFVKX48XD6",    "name": "New queue 2",    "order": 1,    "primary_groups": {      "count": 1,      "groups": [        {          "id": 1100002759994,          "name": "Sales"        }      ]    },    "priority": 10,    "secondary_groups": {      "count": 1,      "groups": [        {          "id": 4398063790591,          "name": "Support"        }      ]    },    "updated_at": "2023-10-13T10:58:25Z",    "url": "https://{subdomain}.zendesk.com/api/v2/queues/01HG80ATNNZK1N7XRFVKX48XD6.json"  }}

Code Samples

curl

curl -X PUT https://{subdomain}.zendesk.com/api/v2/queues/{queue_id}.json \  -H "Content-Type: application/json" \  -d '{ "queue": { "name": "New queue", "description": "Queue description", "definition": { "all": [ { "subject": "priority", "operator": "is", "value": "low", "field": "priority" } ], "any": [] }, "subqueues": [ { "name": "New subqueue update", "priority": 1, "percentage": 20, "primary_groups_id": [4398147357439], "secondary_groups_id": [4398147358079] }, {	"name": "Second subqueue update", "priority": 1, "percentage": 80, "primary_groups_id": [4398147357439], "secondary_groups_id": [] } ] } }' \  -v -u {email_address}/token:{api_token}

Example response(s)

200 OK

// Status 200 OK
{  "queue": {    "url": "https://{subdomain}.zendesk.com/api/v2/queues/01JRDA4FMYF636GG27TVR6HBZ5.json",    "id": "01JRDA4FMYF636GG27TVR6HBZ5",    "name": "New queue",    "description": "Queue description",    "created_at": "2025-04-09T12:59:22Z",    "updated_at": "2025-04-09T13:56:51Z",    "order": 1,    "definition": {      "all": [        {          "field": "priority",          "operator": "is",          "value": "low"        }      ],      "any": []    },    "subqueues": {      "count": 2,      "subqueues": [        {          "id": "01JRDA4FPVQGHKBNZ53F3ZG52K",          "name": "New subqueue update",          "priority": 1,          "percentage": 20,          "primary_groups": {            "count": 1,            "groups": [              {                "id": 4398147357439,                "name": "g1"              }            ]          },          "secondary_groups": {            "count": 1,            "groups": [              {                "id": 4398147358079,                "name": "g2"              }            ]          }        },        {          "id": "01JRDDE32DS17GR07VXF6YC0QH",          "name": "Second subqueue update",          "priority": 1,          "percentage": 80,          "primary_groups": {            "count": 1,            "groups": [              {                "id": 4398147357439,                "name": "g1"              }            ]          },          "secondary_groups": {            "count": 0,            "groups": []          }        }      ]    }  }}

You can update the attributes of a subqueue by including the id in the subqueues object.

Code Samples

curl

curl -X PUT https://{subdomain}.zendesk.com/api/v2/queues/{queue_id}.json \  -H "Content-Type: application/json" \  -d '{ "queue": { "name": "New queue", "description": "Queue description", "definition": { "all": [ { "subject": "priority", "operator": "is", "value": "low", "field": "priority" } ], "any": [] }, "subqueues": [ { "id": "01JS1VH2Q986C5CBAQPSY7E3GA", "name": "New name for subqueue1", "priority": 1, "percentage": 40, "primary_groups_id": [4398147357439], "secondary_groups_id": [4398147358079] }, { "id": "01JS1VH2QSS13QW4SY8WSAHSW0", "name": "New name for subqueue2", "priority": 1, "percentage": 60, "primary_groups_id": [4398147357439], "secondary_groups_id": [] } ] } }' \  -v -u {email_address}/token:{api_token}

Example response(s)

200 OK

// Status 200 OK
{  "queue": {    "url": "https://{subdomain}.zendesk.com/api/v2/queues/01JRDA4FMYF636GG27TVR6HBZ5.json",    "id": "01JRDA4FMYF636GG27TVR6HBZ5",    "name": "New queue",    "description": "Queue description",    "created_at": "2025-04-09T12:59:22Z",    "updated_at": "2025-04-09T13:56:51Z",    "order": 1,    "definition": {      "all": [        {          "field": "priority",          "operator": "is",          "value": "low"        }      ],      "any": []    },    "subqueues": {      "count": 2,      "subqueues": [        {          "id": "01JS1VH2Q986C5CBAQPSY7E3GA",          "name": "New name for subqueue1",          "priority": 1,          "percentage": 40,          "primary_groups": {            "count": 1,            "groups": [              {                "id": 4398147357439,                "name": "g1"              }            ]          },          "secondary_groups": {            "count": 1,            "groups": [              {                "id": 4398147358079,                "name": "g2"              }            ]          }        },        {          "id": "01JS1VH2QSS13QW4SY8WSAHSW0",          "name": "New name for subqueue2",          "priority": 1,          "percentage": 60,          "primary_groups": {            "count": 1,            "groups": [              {                "id": 4398147357439,                "name": "g1"              }            ]          },          "secondary_groups": {            "count": 0,            "groups": []          }        }      ]    }  }}

You can delete a subqueue, for example the one created above, with id 01JS1VH2QSS13QW4SY8WSAHSW0, by omitting it in the subqueues object.

If you omit the subqueues object, all existing subqueues will be deleted.

curl

curl -X PUT https://{subdomain}.zendesk.com/api/v2/queues/{queue_id}.json \  -H "Content-Type: application/json" \  -d '{ "queue": { "name": "New queue", "description": "Queue description", "definition": { "all": [ { "subject": "priority", "operator": "is", "value": "low", "field": "priority" } ], "any": [] }, "subqueues": [ { "id": "01JS1VH2Q986C5CBAQPSY7E3GA", "name": "New subqueue update", "priority": 1, "percentage": 100, "primary_groups_id": [4398147357439], "secondary_groups_id": [4398147358079] } ] } }' \  -v -u {email_address}/token:{api_token}

Example response(s)

200 OK

// Status 200 OK
{  "queue": {    "url": "https://{subdomain}.zendesk.com/api/v2/queues/01JRDA4FMYF636GG27TVR6HBZ5.json",    "id": "01JRDA4FMYF636GG27TVR6HBZ5",    "name": "New queue",    "description": "Queue description",    "created_at": "2025-04-09T12:59:22Z",    "updated_at": "2025-04-09T13:56:51Z",    "order": 1,    "definition": {      "all": [        {          "field": "priority",          "operator": "is",          "value": "low"        }      ],      "any": []    },    "subqueues": {      "count": 2,      "subqueues": [        {          "id": "01JS1VH2Q986C5CBAQPSY7E3GA",          "name": "New subqueue update",          "priority": 1,          "percentage": 100,          "primary_groups": {            "count": 1,            "groups": [              {                "id": 4398147357439,                "name": "g1"              }            ]          },          "secondary_groups": {            "count": 1,            "groups": [              {                "id": 4398147358079,                "name": "g2"              }            ]          }        }      ]    }  }}

Other operations

For all other operations related to queues that are split into subqueues refer to the Queue API documentation for more information.

Agent Availability API

Capacity Rules

Unified Agent Status API

Account Groups Availability API

Omnichannel Engagements

Queues API

Omnichannel Routing Percentage-based Queues API

Example

Create Queue with Subqueues

Allowed For

Details

Code Samples

Example response(s)

Update Queue or Subqueues

Parameters

Details

Code Samples

Example response(s)

Code Samples

Example response(s)

Code Samples

Example response(s)

Example response(s)

Other operations