Skill-based Routing API

The endpoints of the skill-based routing API are for API consumers that want to list attribute (skill types) and attribute values (skills) data, list and set attribute values for ticket and agent.

Attribute

Name Type Comment
id string Automatically assigned when an attribute is created
name string The name of the attribute

Attribute Values

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