Tags

You must enable the tagging of users and organizations in Zendesk Support for the API calls to work. Select Manage > Settings > Customers, and enable the option.

List Tags

GET /api/v2/tags.json

Lists the 500 most popular tags in the last 60 days, in decreasing popularity.

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tags.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "tags": [
    {
      "name":  "important",
      "count": 47
    },
    {
      "name":  "customer",
      "count": 11
    }
  ]
}

Show Tags

GET /api/v2/tickets/{id}/tags.json

GET /api/v2/organizations/{id}/tags.json

GET /api/v2/users/{id}/tags.json

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{id}/tags.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "tags": [
    "important",
    "customer"
  ]
}

Set Tags

POST /api/v2/tickets/{id}/tags.json

POST /api/v2/organizations/{id}/tags.json

POST /api/v2/users/{id}/tags.json

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

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{id}/tags.json \
  -X POST -d '{ "tags": ["important"] }' \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "tags": [
    "important"
  ]
}

Add Tags

PUT /api/v2/tickets/{id}/tags.json

PUT /api/v2/organizations/{id}/tags.json

PUT /api/v2/users/{id}/tags.json

You can also add tags to multiple tickets with the Update Many Tickets endpoint.

Safe Update

If the same ticket is updated by multiple API requests at the same time, some tags could be lost because of ticket update collisions. Include updated_stamp and safe_update properties in the request body to make a safe update.

For updated_stamp, retrieve and specify the ticket's latest updated_at timestamp. The tag update only occurs if the updated_stamp timestamp matches the ticket's actual updated_at timestamp at the time of the request. If the timestamps don't match (in other words, if the ticket was updated since you retrieved the ticket's last updated_at timestamp), the request returns a 409 Conflict error.

Example

{
  "tags": ["customer"],
  "updated_stamp":"2019-09-12T21:45:16Z",
  "safe_update":"true"
}

For details, see Protect against ticket update collisions.

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{id}/tags.json \
  -X PUT -d '{ "tags": ["customer"] }' \
  -H "Content-Type: application/json" -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "tags": [
    "important",
    "customer"
  ]
}

Remove Tags

DELETE /api/v2/tickets/{id}/tags.json

DELETE /api/v2/organizations/{id}/tags.json

DELETE /api/v2/users/{id}/tags.json

You can also delete tags from multiple tickets with the Update Many Tickets endpoint.

This endpoint supports safe updates. See Safe Update.

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{id}/tags.json \
  -X DELETE -d '{ "tags": ["customer"] }' \
  -H "Content-Type: application/json" -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "tags": [
    "important"
  ]
}

Autocomplete Tags

GET /api/v2/autocomplete/tags.json?name={name}

Returns an array of registered and recent tag names that start with the specified name. The name must be at least 2 characters in length.

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/autocomplete/tags.json?name=att \
  -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "tags": [ "attention", "attack" ]
}