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

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

  • Agents

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

Search Tags

  • GET /api/v2/autocomplete/tags

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

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

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

List Resource 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"  ]}

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/tickets/{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"  ]}

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/tickets/{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"  ]}

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