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 |
List Tags
GET /api/v2/tags
Lists up to the 20,000 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
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/tags.json \
-v -u {email_address}:{password}
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://example.zendesk.com/api/v2/tags"
method := "GET"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/tags")
.newBuilder();
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'GET',
url: 'https://example.zendesk.com/api/v2/tags',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
url = "https://example.zendesk.com/api/v2/tags"
headers = {
"Content-Type": "application/json",
}
response = requests.request(
"GET",
url,
auth=('<username>', '<password>'),
headers=headers
)
print(response.text)
Ruby
require "net/http"
uri = URI("https://example.zendesk.com/api/v2/tags")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
200 OK
// 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.
Pagination
- Offset pagination only
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
name | string | Query | false | A substring of a tag to search for |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/autocomplete/tags.json?name=att \
-u {email_address}:{password}
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://example.zendesk.com/api/v2/autocomplete/tags?name=att"
method := "GET"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/autocomplete/tags")
.newBuilder()
.addQueryParameter("name", "att");
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'GET',
url: 'https://example.zendesk.com/api/v2/autocomplete/tags',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
},
params: {
'name': 'att',
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
url = "https://example.zendesk.com/api/v2/autocomplete/tags?name=att"
headers = {
"Content-Type": "application/json",
}
response = requests.request(
"GET",
url,
auth=('<username>', '<password>'),
headers=headers
)
print(response.text)
Ruby
require "net/http"
uri = URI("https://example.zendesk.com/api/v2/autocomplete/tags")
uri.query = URI.encode_www_form("name": "att")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
200 OK
// 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
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/tags/count.json \
-v -u {email_address}:{password}
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://example.zendesk.com/api/v2/tags/count"
method := "GET"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/tags/count")
.newBuilder();
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'GET',
url: 'https://example.zendesk.com/api/v2/tags/count',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
url = "https://example.zendesk.com/api/v2/tags/count"
headers = {
"Content-Type": "application/json",
}
response = requests.request(
"GET",
url,
auth=('<username>', '<password>'),
headers=headers
)
print(response.text)
Ruby
require "net/http"
uri = URI("https://example.zendesk.com/api/v2/tags/count")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
200 OK
// 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 |
Code Samples
curl
curl https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}/tags.json \
-v -u {email_address}:{password}
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://example.zendesk.com/api/v2/tickets/123456/tags"
method := "GET"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/tickets/123456/tags")
.newBuilder();
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("GET", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'GET',
url: 'https://example.zendesk.com/api/v2/tickets/123456/tags',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
url = "https://example.zendesk.com/api/v2/tickets/123456/tags"
headers = {
"Content-Type": "application/json",
}
response = requests.request(
"GET",
url,
auth=('<username>', '<password>'),
headers=headers
)
print(response.text)
Ruby
require "net/http"
uri = URI("https://example.zendesk.com/api/v2/tickets/123456/tags")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
200 OK
// 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 |
Code Samples
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}
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://example.zendesk.com/api/v2/tickets/123456/tags"
method := "PUT"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/tickets/123456/tags")
.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
"""
""");
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("PUT", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'PUT',
url: 'https://example.zendesk.com/api/v2/tickets/123456/tags',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
url = "https://example.zendesk.com/api/v2/tickets/123456/tags"
headers = {
"Content-Type": "application/json",
}
response = requests.request(
"PUT",
url,
auth=('<username>', '<password>'),
headers=headers
)
print(response.text)
Ruby
require "net/http"
uri = URI("https://example.zendesk.com/api/v2/tickets/123456/tags")
request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
200 OK
// 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 |
Code Samples
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}
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://example.zendesk.com/api/v2/tickets/123456/tags"
method := "POST"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/tickets/123456/tags")
.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
"""
""");
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'POST',
url: 'https://example.zendesk.com/api/v2/tickets/123456/tags',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
url = "https://example.zendesk.com/api/v2/tickets/123456/tags"
headers = {
"Content-Type": "application/json",
}
response = requests.request(
"POST",
url,
auth=('<username>', '<password>'),
headers=headers
)
print(response.text)
Ruby
require "net/http"
uri = URI("https://example.zendesk.com/api/v2/tickets/123456/tags")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
201 Created
// 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 |
Code Samples
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}
Go
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://example.zendesk.com/api/v2/tickets/123456/tags"
method := "DELETE"
req, err := http.NewRequest(method, url, nil)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
client := &http.Client {}
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Java
import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/tickets/123456/tags")
.newBuilder();
Request request = new Request.Builder()
.url(urlBuilder.build())
.method("DELETE", null)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
.build();
Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {
method: 'DELETE',
url: 'https://example.zendesk.com/api/v2/tickets/123456/tags',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
},
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python
import requests
url = "https://example.zendesk.com/api/v2/tickets/123456/tags"
headers = {
"Content-Type": "application/json",
}
response = requests.request(
"DELETE",
url,
auth=('<username>', '<password>'),
headers=headers
)
print(response.text)
Ruby
require "net/http"
uri = URI("https://example.zendesk.com/api/v2/tickets/123456/tags")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
http.request(request)
end
Example response(s)
204 No Content
// Status 204 No Content
null