Tags

You must enable the tagging of users and organizations in Zendesk Support for the API calls to work. In Support, click the Admin icon in the sidebar, select Settings > Customers, and enable the option.

JSON Format

Tags are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
tags array false true An array of strings

Autocomplete Tags

  • GET /api/v2/autocomplete/tags

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

Allowed For
  • Agents
Parameters
Name Type In Required Description
tag_name_fragment string Query false A substring of a tag to search for
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"
  ]
}

List Tags

  • GET /api/v2/tags

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

Pagination
  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

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

{
  "count": 1,
  "next_page": null,
  "previous_page": null,
  "tags": [
    {
      "count": 10,
      "name": "Triage"
    }
  ]
}

Count Tags

  • GET /api/v2/tags/count

Returns an approximate count of tags. If the count exceeds 100,000, it is updated every 24 hours.

The refreshed_at property of the count object is a timestamp that indicates when the count was last updated.

Note: When the count exceeds 100,000, the refreshed_at property in the count object may occasionally be null. This indicates that the count is being updated in the background and the value property in the count object is limited to 100,000 until the update is complete.

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

{
  "count": {
    "refreshed_at": "2020-04-06T02:18:17Z",
    "value": 102
  }
}

Show Tags

  • GET /api/v2/tickets/{ticket_id}/tags
  • GET /api/v2/organizations/{organization_id}/tags
  • GET /api/v2/users/{user_id}/tags
Allowed For
  • Agents
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/tickets/{ticket_id}/tags.json \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "tags": [
    "urgent",
    "printer",
    "fire"
  ]
}

Set Tags

  • POST /api/v2/tickets/{ticket_id}/tags
  • POST /api/v2/organizations/{organization_id}/tags
  • POST /api/v2/users/{user_id}/tags
Allowed For
  • Agents
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/ticket/{ticket_id}/tags.json \
  -X POST -d '{ "tags": ["important"] }' \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password}
Example Response
Status 201 Created

{
  "tags": [
    "urgent",
    "printer",
    "fire"
  ]
}

Add Tags

  • PUT /api/v2/tickets/{ticket_id}/tags
  • PUT /api/v2/organizations/{organization_id}/tags
  • PUT /api/v2/users/{user_id}/tags

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 Protecting against ticket update collisions.

Allowed For
  • Agents
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/ticket/{ticket_id}/tags.json \
  -X PUT -d '{ "tags": ["customer"] }' \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "tags": [
    "urgent",
    "printer",
    "fire"
  ]
}

Remove Tags

  • DELETE /api/v2/tickets/{ticket_id}/tags
  • DELETE /api/v2/organizations/{organization_id}/tags
  • DELETE /api/v2/users/{user_id}/tags

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
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/tickets/{ticket_id}/tags.json \
  -X DELETE -d '{ "tags": ["customer"] }' \
  -H "Content-Type: application/json" -v -u {email_address}:{password}
Example Response
Status 204 No Content