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.

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

List Account Attributes

GET /api/v2/routing/attributes.json

Returns a list of attributes for the account.

Allowed For
  • Agents and admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/attributes.json \
  -v -u {email_address}:{password}
Sideloads

The following sideloads are supported:

Name Will sideload
attribute_values The attribute values available on the account
Example Response
Status: 200 OK

 {
   "attributes": [{
     "id": "15821cba-7326-11e8-b07e-950ba849aa27",
     "name": "Color",
     "created_at": "2017-12-01T19:29:31Z",
     "updated_at": "2017-12-01T19:29:31Z"
   }]
 }

Create Attribute

POST /api/v2/routing/attributes.json

Creates an attribute.

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/attributes.json \
  -H "Content-Type: application/json" \
  -d '{"attribute_value": { "name": "Language" }}' \
  -v -u {email_address}:{password}
Example Response
Status: 201 Created

{
  "attribute": {
    "url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/6e279587-e930-11e8-a292-09cfcdea1b75.json",
    "id": "6e279587-e930-11e8-a292-09cfcdea1b75",
    "name": "Language",
    "created_at": "2018-11-15T23:44:45Z",
    "updated_at": "2018-11-15T23:44:45Z"
  }
}

Show Attribute

`GET /api/v2/routing/attributes/{attribute_id}.json

Returns an attribute.

Allowed For
  • Admins
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": {
    "url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/6e279587-e930-11e8-a292-09cfcdea1b75.json",
    "id": "6e279587-e930-11e8-a292-09cfcdea1b75",
    "name": "Language",
    "created_at": "2018-11-15T23:44:45Z",
    "updated_at": "2018-11-15T23:44:45Z"
  }
}

Update Attribute

PATCH /api/v2/routing/attributes/{attribute_id}.json

Updates an attribute.

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/attributes/{attribute_id}.json \
  -X PATCH -H "Content-Type: application/json" \
  -d '{ "name": "Lingua" }' \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "attribute": {
    "url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/6e279587-e930-11e8-a292-09cfcdea1b75.json",
    "id": "6e279587-e930-11e8-a292-09cfcdea1b75",
    "name": "Lingua",
    "created_at": "2018-11-15T23:44:45Z",
    "updated_at": "2018-11-15T23:44:45Z"
  }
}

Delete Attribute

DELETE /api/v2/routing/attributes/{attribute_id}.json

Deletes an attribute.

Allowed For
  • Admins
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 Routing Attribute Definitions

GET /api/v2/routing/attributes/definitions.json

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": [
       {
          "title": "Number of incidents",
          "subject": "number_of_incidents",
          ...
       }
     ],
    "conditions_any": [...]
  }
}

List Attribute Values for an Attribute

GET /api/v2/routing/attributes/{attribute_id}/values.json

Returns a list of attribute values for a provided attribute.

Allowed For
  • Admins
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": [
    {
      "url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/afa31619-e38b-11e8-a292-5d17513d969b/values/b376b35a-e38b-11e8-a292-e3b6377c5575.json",
      "id": "b376b35a-e38b-11e8-a292-e3b6377c5575",
      "name": "French",
      "created_at": "2018-11-08T19:22:58Z",
      "updated_at": "2018-11-08T19:22:58Z"
    }
  ]
}

Create Attribute Value

POST /api/v2/routing/attributes/{attribute_id}/values.json

Creates an attribute value.

Allowed For
  • Admins
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

{
  {
    "url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/afa31619-e38b-11e8-a292-5d17513d969b/values/6ccddacf-e85e-11e8-a292-ad7686bdff67.json",
    "id": "6ccddacf-e85e-11e8-a292-ad7686bdff67
    "name": "Japanese",
    "created_at": "2018-11-08T19:22:58Z",
    "updated_at": "2018-11-08T19:22:58Z"
  }
}

Show Attribute Value

GET /api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}.json

Returns an attribute value.

Allowed For
  • Admins
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

{
  {
    "url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/afa31619-e38b-11e8-a292-5d17513d969b/values/b376b35a-e38b-11e8-a292-e3b6377c5575.json",
    "id": "b376b35a-e38b-11e8-a292-e3b6377c5575",
    "name": "French",
    "created_at": "2018-11-08T19:22:58Z",
    "updated_at": "2018-11-08T19:22:58Z"
  }
}

Update Attribute Value

PATCH /api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}.json

Updates an attribute value.

Allowed For
  • Admins
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

{
  {
    "url": "https://{subdomain}.zendesk.com/api/v2/routing/attributes/afa31619-e38b-11e8-a292-5d17513d969b/values/b376b35a-e38b-11e8-a292-e3b6377c5575.json",
    "id": "b376b35a-e38b-11e8-a292-e3b6377c5575",
    "name": "German (Advanced)",
    "created_at": "2018-11-14T22:41:28Z",
    "updated_at": "2018-11-14T22:45:01Z"
  }
}

Delete Attribute Value

DELETE /api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}.json

Deletes an attribute value.

Allowed For
  • Agents
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 Ticket Attribute Values

GET /api/v2/routing/tickets/{ticket_id}/instance_values.json

Returns a list of attributes values for the ticket.

Allowed For
  • Agents and admins
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": [{
   "id": "fa1131e2-d6cd-11e7-a492-dbdd5500c7e3",
   "name": "Ocean",
   "created_at": "2017-12-01T19:29:41Z",
   "updated_at": "2017-12-01T19:35:45Z",
   "attribute_id": "f4a604b1-d6cd-11e7-a492-657e7928664c"
 }]
}

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.

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/tickets/{ticket_id}/instance_values \
  -H "Content-Type: application/json" \
  --data "{\"attribute_value_ids\":[\"{attribute_value_id}\"]}" \
  -v -u {email_address}:{password} -X POST
Example Response
Status: 200 OK

{
 "attribute_values": [{
   "id": "fa1131e2-d6cd-11e7-a492-dbdd5500c7e3",
   "name": "Ocean",
   "created_at": "2017-12-01T19:29:41Z",
   "updated_at": "2017-12-01T19:35:45Z",
   "attribute_id": "f4a604b1-d6cd-11e7-a492-657e7928664c"
 }]
}

List Agent Attribute Values

GET /api/v2/routing/agents/{agent_id}/instance_values.json

Returns a list of attributes values for the agent.

Allowed For
  • Agents and admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/agents/{agent_id}/instance_values.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
 "attribute_values": [{
   "id": "fa1131e2-d6cd-11e7-a492-dbdd5500c7e3",
   "name": "Ocean",
   "created_at": "2017-12-01T19:29:41Z",
   "updated_at": "2017-12-01T19:35:45Z",
   "attribute_id": "f4a604b1-d6cd-11e7-a492-657e7928664c"
 }]
}

Set Agent Attribute Values

POST /api/v2/routing/agents/{agent_id}/instance_values

Adds the specified attributes if no attributes exists, or replaces all existing attributes with the specified attributes.

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/routing/agents/{agent_id}/instance_values \
  -H "Content-Type: application/json" \
  --data "{\"attribute_value_ids\":[\"{attribute_value_id}\"]}" \
  -v -u {email_address}:{password} -X POST
Example Response
Status: 200 OK

{
 "attribute_values": [{
   "id": "fa1131e2-d6cd-11e7-a492-dbdd5500c7e3",
   "name": "Ocean",
   "created_at": "2017-12-01T19:29:41Z",
   "updated_at": "2017-12-01T19:35:45Z",
   "attribute_id": "f4a604b1-d6cd-11e7-a492-657e7928664c"
 }]
}

List Tickets Fulfilled by a User

GET /api/v2/routing/requirements/fulfilled.json

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
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]
 }