Skill-based Routing
You can use the skill-based routing API to list skill types and skills, as well as list and set skills for tickets and agents. To learn more about the feature, see Using skills-based routing in the Support Help Center.
In this API, skill types are named attributes and skills are named attribute values.
Skill-based routing is only available on the Enterprise plan and above.
Attribute
An attribute in this API refers to a skill type. Skill types are categories of skills.
Name | Type | Comment |
---|---|---|
id | string | Automatically assigned when an attribute is created |
name | string | The name of the attribute |
Attribute Values
An attribute value in this API refers to a skill. Skills are associated with an agent and determine the agent's suitability to solve a ticket.
Name | Type | Comment |
---|---|---|
id | string | Automatically assigned when an attribute value is created |
name | string | The name of the attribute value |
attribute_id | string | Id of the associated attribute |
JSON Format
Skill Based Routing are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
created_at | string | true | false | When this record was created |
id | string | true | false | Automatically assigned when an attribute is created |
name | string | false | true | The name of the attribute |
updated_at | string | true | false | When this record was last updated |
url | string | true | false | URL of the attribute |
Example
{
"created_at": "2017-12-01T19:29:31Z",
"id": "15821cba-7326-11e8-b07e-950ba849aa27",
"name": "color",
"updated_at": "2017-12-01T19:29:31Z",
"url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/15821cba-7326-11e8-b07e-950ba849aa27.json"
}
List Account Attributes
GET /api/v2/routing/attributes
Returns a list of attributes for the account.
Sideloads
The following sideloads are supported:
Name | Will sideload |
---|---|
attribute_values | The attribute values available on the account |
Allowed For
- Agents and admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/automations.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"attributes": [
{
"created_at": "2017-12-01T19:29:31Z",
"id": "15821cba-7326-11e8-b07e-950ba849aa27",
"name": "Color",
"updated_at": "2017-12-01T19:29:31Z"
}
],
"count": 1,
"next_page": null,
"previous_page": null
}
List Routing Attribute Definitions
GET /api/v2/routing/attributes/definitions
Returns the condition definitions that can be configured to apply attributes to a ticket.
Allowed For
- Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/attributes/definitions.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"definitions": {
"conditions_all": [
{
"subject": "number_of_incidents",
"title": "Number of incidents"
}
],
"conditions_any": [
{
"subject": "brand",
"title": "Brand"
}
]
}
}
Show Attribute
GET /api/v2/routing/attributes/{attribute_id}
Returns an attribute.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
attribute_id | string | Path | true | The ID of the skill-based routing attribute |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/attributes/{attribute_id}.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"attribute": {
"created_at": "2018-11-15T23:44:45Z",
"id": "6e279587-e930-11e8-a292-09cfcdea1b75",
"name": "Language",
"updated_at": "2018-11-15T23:44:45Z",
"url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/6e279587-e930-11e8-a292-09cfcdea1b75.json"
}
}
Create Attribute
POST /api/v2/routing/attributes
Creates an attribute.
Allowed For
- Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/attributes.json \
-H "Content-Type: application/json" \
-d '{"attribute": { "name": "Language" }}' \
-v -u {email_address}:{password}
Example Response
Status 201 Created
{
"attribute": {
"created_at": "2018-11-15T23:44:45Z",
"id": "6e279587-e930-11e8-a292-09cfcdea1b75",
"name": "Language",
"updated_at": "2018-11-15T23:44:45Z",
"url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/6e279587-e930-11e8-a292-09cfcdea1b75.json"
}
}
Update Attribute
PUT /api/v2/routing/attributes/{attribute_id}
Updates an attribute.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
attribute_id | string | Path | true | The ID of the skill-based routing attribute |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/attributes/{attribute_id}.json \
-d '{ "name": "Lingua" }' \
-X PATCH -H "Content-Type: application/json" \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"attribute": {
"created_at": "2018-11-15T23:44:45Z",
"id": "6e279587-e930-11e8-a292-09cfcdea1b75",
"name": "Lingua",
"updated_at": "2018-11-15T23:44:45Z",
"url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/6e279587-e930-11e8-a292-09cfcdea1b75.json"
}
}
Delete Attribute
DELETE /api/v2/routing/attributes/{attribute_id}
Deletes an attribute.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
attribute_id | string | Path | true | The ID of the skill-based routing attribute |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/attributes/{attribute_id}.json \
-X DELETE -v -u {email_address}:{password}
Example Response
Status 204 No Content
List Attribute Values for an Attribute
GET /api/v2/routing/attributes/{attribute_id}/values
Returns a list of attribute values for a provided attribute.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
attribute_id | string | Path | true | The ID of the skill-based routing attribute |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/attributes/{attribute_id}/values.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"attribute_values": [
{
"created_at": "2018-11-08T19:22:58Z",
"id": "b376b35a-e38b-11e8-a292-e3b6377c5575",
"name": "French",
"updated_at": "2018-11-08T19:22:58Z",
"url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/afa31619-e38b-11e8-a292-5d17513d969b/values/b376b35a-e38b-11e8-a292-e3b6377c5575.json"
}
]
}
Show Attribute Value
GET /api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}
Returns an attribute value.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
attribute_id | string | Path | true | The ID of the skill-based routing attribute |
attribute_value_id | string | Path | true | The ID of the skill-based routing attribute value |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id} \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"attribute_value": {
"created_at": "2018-11-08T19:22:58Z",
"id": "b376b35a-e38b-11e8-a292-e3b6377c5575",
"name": "French",
"updated_at": "2018-11-08T19:22:58Z",
"url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/afa31619-e38b-11e8-a292-5d17513d969b/values/b376b35a-e38b-11e8-a292-e3b6377c5575.json"
}
}
Create Attribute Value
POST /api/v2/routing/attributes/{attribute_id}/values
Creates an attribute value.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
attribute_id | string | Path | true | The ID of the skill-based routing attribute |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/attributes/{attribute_id}/values.json \
-H "Content-Type: application/json" \
-d '{"attribute_value": { "name": "Japanese" }}' \
-v -u {email_address}:{password}
Example Response
Status 201 Created
{
"attribute_value": {
"created_at": "2018-11-08T19:22:58Z",
"id": "6ccddacf-e85e-11e8-a292-ad7686bdff67",
"name": "Japanese",
"updated_at": "2018-11-08T19:22:58Z",
"url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/afa31619-e38b-11e8-a292-5d17513d969b/values/6ccddacf-e85e-11e8-a292-ad7686bdff67.json"
}
}
Update Attribute Value
PATCH /api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}
Updates an attribute value.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
attribute_id | string | Path | true | The ID of the skill-based routing attribute |
attribute_value_id | string | Path | true | The ID of the skill-based routing attribute value |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}.json \
-X PATCH -H "Content-Type: application/json" \
-d '{ "name": "German (Advanced)" }' \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"attribute_value": {
"created_at": "2018-11-14T22:41:28Z",
"id": "b376b35a-e38b-11e8-a292-e3b6377c5575",
"name": "German (Advanced)",
"updated_at": "2018-11-14T22:45:01Z",
"url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/afa31619-e38b-11e8-a292-5d17513d969b/values/b376b35a-e38b-11e8-a292-e3b6377c5575.json"
}
}
Delete Attribute Value
DELETE /api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}
Deletes an attribute value.
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
attribute_id | string | Path | true | The ID of the skill-based routing attribute |
attribute_value_id | string | Path | true | The ID of the skill-based routing attribute value |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}.json \
-X DELETE -v -u {email_address}:{password}
Example Response
Status 204 No Content
List Agent Attribute Values
GET /api/v2/routing/agents/{user_id}/instance_values
Returns an attribute value.
Allowed For
- Agents and admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
user_id | integer | Path | true | The ID of the user |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/agents/{user_id}/instance_values.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"attribute_values": [
{
"created_at": "2018-11-08T19:22:58Z",
"id": "b376b35a-e38b-11e8-a292-e3b6377c5575",
"name": "French",
"updated_at": "2018-11-08T19:22:58Z",
"url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/afa31619-e38b-11e8-a292-5d17513d969b/values/b376b35a-e38b-11e8-a292-e3b6377c5575.json"
}
]
}
Set Agent Attribute Values
POST /api/v2/routing/agents/{user_id}/instance_values
Adds the specified attributes if no attributes exists, or replaces all existing attributes with the specified attributes.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
user_id | integer | Path | true | The ID of the user |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/agents/{user_id}/instance_values \
-d "{\"attribute_value_ids\":[\"{attribute_value_id}\"]}" \
-H "Content-Type: application/json" \
-v -u {email_address}:{password} -X POST
Example Response
Status 200 OK
{
"attribute_values": [
{
"created_at": "2018-11-08T19:22:58Z",
"id": "b376b35a-e38b-11e8-a292-e3b6377c5575",
"name": "French",
"updated_at": "2018-11-08T19:22:58Z",
"url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/afa31619-e38b-11e8-a292-5d17513d969b/values/b376b35a-e38b-11e8-a292-e3b6377c5575.json"
}
]
}
List Ticket Attribute Values
GET /api/v2/routing/tickets/{ticket_id}/instance_values
Returns a list of attributes values for the ticket.
Allowed For
- Agents and admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/tickets/{ticket_id}/instance_values.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"attribute_values": [
{
"attribute_id": "f4a604b1-d6cd-11e7-a492-657e7928664c",
"created_at": "2017-12-01T19:29:41Z",
"id": "fa1131e2-d6cd-11e7-a492-dbdd5500c7e3",
"name": "Ocean",
"updated_at": "2017-12-01T19:35:45Z"
}
]
}
Set Ticket Attribute Values
POST /api/v2/routing/tickets/{ticket_id}/instance_values
Adds the specified attributes if no attributes exists, or replaces all existing attributes with the specified attributes.
Invalid or deleted attributes are ignored.
Allowed For
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_id | integer | Path | true | The ID of the ticket |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/tickets/{ticket_id}/instance_values \
-d "{\"attribute_value_ids\":[\"{attribute_value_id}\"]}" \
-H "Content-Type: application/json" \
-v -u {email_address}:{password} -X POST
Example Response
Status 200 OK
{
"attribute_values": [
{
"attribute_id": "f4a604b1-d6cd-11e7-a492-657e7928664c",
"created_at": "2017-12-01T19:29:41Z",
"id": "fa1131e2-d6cd-11e7-a492-dbdd5500c7e3",
"name": "Ocean",
"updated_at": "2017-12-01T19:35:45Z"
}
]
}
List Tickets Fulfilled by a User
GET /api/v2/routing/requirements/fulfilled
Returns a list of ticket ids that contain attributes matching the current user's attributes. Accepts a ticket_ids
parameter for relevant tickets to check for matching attributes.
Allowed For
- Agents and admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ticket_ids | integer | Path | true | The IDs of the relevant tickets to check for matching attributes |
Using curl
curl 'https://{subdomain}.zendesk.com/api/v2/routing/requirements/fulfilled?ticket_ids\[\]=17&ticket_ids\[\]=1&ticket_ids\[\]=99' \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"fulfilled_ticket_ids": [
1,
17
]
}