You can use the API to get or set agent information.

If you created your Zendesk Chat account in Zendesk Support, access to the Chat Accounts and Agents APIs is restricted to GET requests. You can still use the other Chat APIs normally.

JSON format

Agents are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
create_datestringtruefalseThe date of creation of the agent
departmentsarraytruefalseThe departments for the agent
display_namestringfalsefalseThe name to be displayed for the agent
emailstringfalsefalseThe email address of the agent
enabledintegerfalsefalseDescribes whether the agent is enabled
enabled_departmentsarraytruefalseThe enabled departments for the agent
first_namestringfalsefalseThe agent's first name
idintegertruefalseThe ID of the agent
last_namestringfalsefalseThe agent's last name
role_idintegerfalsefalseThe role ID of the agent
rolesobjecttruefalseSpecial role privileges. See below for values (deprecated)
skillsarraytruefalseThe skills for the agent

The roles attribute has the following values:

ValueUsers
ownerowner of the account
administratoragent with administrator privileges

Note: The following field is required during creation:

NameTypeRead-onlyDescription
passwordstringyesThis is the password for the agent. This is only required during creation.

Example

{  "create_date": "2014-09-30T08:25:09Z",  "departments": [],  "display_name": "Johnny",  "email": "[email protected]",  "enabled": 1,  "enabled_departments": [],  "first_name": "John",  "id": 5,  "last_name": "Doe",  "role_id": 3,  "roles": {    "administrator": false,    "owner": false  }}

List Agents

  • GET /api/v2/agents

Lists all the agents for your account.

Pagination

This endpoint uses cursor-based pagination. The records are ordered sequentially by record id. The endpoint takes max_id and since_id query parameters, which act as separate cursors that track the record ids in the recordset. The max_id cursor moves backward through the recordset, with the record ids getting smaller. The since_id cursor moves forward, with the record ids getting larger.

  • Use the max_id parameter to paginate backward through the recordset. Example: "Get the previous 200 records, ending with and including the max_id record."

    "https://www.zopim.com/api/v2/agents?max_id=10&limit=200"

  • Use the since_id parameter to paginate forward through the recordset. Example: "Get the next 200 records, starting with and including the since_id record."

    "https://www.zopim.com/api/v2/agents?since_id=10&limit=200"

The next page can be retrieved by computing the next since_id by adding 1 to the ID of the last record in the current set, and specifying that as the since_id in the next request. Similarly, the previous page can be retrieved by making a request that species a max_id that is 1 less than the first element of the current record set.

Additionally, the next page and the previous page paths will be available as headers in the response.

If any of the pagination parameters (since_id, max_id, limit) are present, the default number of results is 10, but you can change it with the limit parameter. If none of the pagination parameters are present, the entire record set is returned.

Zendesk Chat recommends using pagination wherever possible. Non-paginated queries will be deprecated in subsequent releases of the API.

Allowed for

  • Agent

Parameters

NameTypeInRequiredDescription
limitintegerQueryfalseNumber of records that will be returned by the endpoint. Default to 10.
max_idintegerQueryfalseUse the max_id parameter to paginate backward through the recordset
since_idintegerQueryfalseUse the since_id parameter to paginate forward through the recordset

Code Samples

curl
curl "https://www.zopim.com/api/v2/agents?since_id=5&limit=2" \  -v -H "Authorization: Bearer {token}"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://www.zopim.com/api/v2/agents?limit=20&max_id=20&since_id=10"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	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://www.zopim.com/api/v2/agents")		.newBuilder()		.addQueryParameter("limit", "20")		.addQueryParameter("max_id", "20")		.addQueryParameter("since_id", "10");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://www.zopim.com/api/v2/agents',  headers: {	'Content-Type': 'application/json',  },  params: {    'limit': '20',    'max_id': '20',    'since_id': '10',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://www.zopim.com/api/v2/agents?limit=20&max_id=20&since_id=10"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://www.zopim.com/api/v2/agents")uri.query = URI.encode_www_form("limit": "20", "max_id": "20", "since_id": "10")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")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
[  {    "create_date": "2014-09-30T08:25:09Z",    "departments": [],    "display_name": "Johnny",    "email": "[email protected]",    "enabled": 1,    "first_name": "John",    "id": 5,    "last_name": "Doe",    "role_id": 3,    "roles": {      "administrator": false,      "owner": false    }  }]

Show Agent by ID

  • GET /api/v2/agents/{agent_id}

Fetches an agent by his or her ID.

Allowed for

  • Administrator

Parameters

NameTypeInRequiredDescription
agent_idintegerPathtrueThe ID of the agent

Code Samples

curl
curl https://www.zopim.com/api/v2/agents/{agent_id} \  -v -H "Authorization: Bearer {token}"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://www.zopim.com/api/v2/agents/1"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	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://www.zopim.com/api/v2/agents/1")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://www.zopim.com/api/v2/agents/1',  headers: {	'Content-Type': 'application/json',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://www.zopim.com/api/v2/agents/1"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://www.zopim.com/api/v2/agents/1")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")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
{  "create_date": "2014-09-30T08:25:09Z",  "departments": [],  "display_name": "Johnny",  "email": "[email protected]",  "enabled": 1,  "enabled_departments": [],  "first_name": "John",  "id": 5,  "last_name": "Doe",  "role_id": 3,  "roles": {    "administrator": false,    "owner": false  }}

Show Agent by Email

  • GET /api/v2/agents/email/{email}

Fetches an agent using the agent's email address.

Allowed for

  • Administrator

Parameters

NameTypeInRequiredDescription
emailstringPathtrueThe email of the agent

Code Samples

curl
curl "https://www.zopim.com/api/v2/agents/email/{email_id}" \  -v -H "Authorization: Bearer {token}"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://www.zopim.com/api/v2/agents/email/[email protected]"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	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://www.zopim.com/api/v2/agents/email/[email protected]")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://www.zopim.com/api/v2/agents/email/[email protected]',  headers: {	'Content-Type': 'application/json',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://www.zopim.com/api/v2/agents/email/[email protected]"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://www.zopim.com/api/v2/agents/email/[email protected]")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")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
{  "create_date": "2014-09-30T08:25:09Z",  "departments": [],  "display_name": "Johnny",  "email": "[email protected]",  "enabled": 1,  "enabled_departments": [],  "first_name": "John",  "id": 5,  "last_name": "Doe",  "role_id": 3,  "roles": {    "administrator": false,    "owner": false  }}

Show Requesting Agent

  • GET /api/v2/agents/me

Fetches your data.

Allowed for

  • Agent

Code Samples

curl
curl https://www.zopim.com/api/v2/agents/me \  -v -H "Authorization: Bearer {token}"
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://www.zopim.com/api/v2/agents/me"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	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://www.zopim.com/api/v2/agents/me")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://www.zopim.com/api/v2/agents/me',  headers: {	'Content-Type': 'application/json',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://www.zopim.com/api/v2/agents/me"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://www.zopim.com/api/v2/agents/me")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")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
{  "create_date": "2014-09-30T08:25:09Z",  "departments": [],  "display_name": "Johnny",  "email": "[email protected]",  "enabled": 1,  "enabled_departments": [],  "first_name": "John",  "id": 5,  "last_name": "Doe",  "role_id": 3,  "roles": {    "administrator": false,    "owner": false  }}

Create Agent

  • POST /api/v2/agents

Creates an agent in an account. Note: An additional field, password, needs to be provided during creation.

Allowed for

  • Administrator

Code Samples

curl
curl https://www.zopim.com/api/v2/agents \  -d '{      "email": "[email protected]",      "password": "secretpassword",      "first_name": "John",      "last_name": "Smith",      "display_name": "Smith",      "enabled": 1    }' \-v -H "Authorization: Bearer {token}" \-H "Content-Type: application/json" -X POST
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://www.zopim.com/api/v2/agents"	method := "POST"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	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://www.zopim.com/api/v2/agents")		.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")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'POST',  url: 'https://www.zopim.com/api/v2/agents',  headers: {	'Content-Type': 'application/json',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://www.zopim.com/api/v2/agents"headers = {	"Content-Type": "application/json",}
response = requests.request(	"POST",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://www.zopim.com/api/v2/agents")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")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
{  "display_name": "Smith",  "email": "[email protected]",  "enabled": 1,  "first_name": "John",  "last_name": "Smith"}

Update Agent

  • PUT /api/v2/agents/{agent_id}

Updates details of an agent.

Allowed for

  • Administrator

Parameters

NameTypeInRequiredDescription
agent_idintegerPathtrueThe ID of the agent

Code Samples

curl
curl https://www.zopim.com/api/v2/agents/{agent_id} \  -d '{"first_name": "John", "last_name": "Smith", "role_id": 2}' \  -v -H "Authorization: Bearer {token}" \  -H "Content-Type: application/json" -X PUT
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://www.zopim.com/api/v2/agents/1"	method := "PUT"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	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://www.zopim.com/api/v2/agents/1")		.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")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'PUT',  url: 'https://www.zopim.com/api/v2/agents/1',  headers: {	'Content-Type': 'application/json',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://www.zopim.com/api/v2/agents/1"headers = {	"Content-Type": "application/json",}
response = requests.request(	"PUT",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://www.zopim.com/api/v2/agents/1")request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")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
{  "display_name": "Smith",  "email": "[email protected]",  "enabled": 1,  "first_name": "John",  "last_name": "Smith"}

Update Requesting Agent

  • PUT /api/v2/agents/me

Updates your data.

Allowed for

  • Administrator

Code Samples

curl
curl https://www.zopim.com/api/v2/agents/me \  -d '{"first_name" : "Jonathan"}' \  -v -H "Authorization: Bearer {token}" \  -H "Content-Type: application/json" -X PUT
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://www.zopim.com/api/v2/agents/me"	method := "PUT"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	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://www.zopim.com/api/v2/agents/me")		.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")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'PUT',  url: 'https://www.zopim.com/api/v2/agents/me',  headers: {	'Content-Type': 'application/json',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://www.zopim.com/api/v2/agents/me"headers = {	"Content-Type": "application/json",}
response = requests.request(	"PUT",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://www.zopim.com/api/v2/agents/me")request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")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
{  "display_name": "Smith",  "email": "[email protected]",  "enabled": 1,  "first_name": "John",  "last_name": "Smith"}

Delete Agent

  • DELETE /api/v2/agents/{agent_id}

Deletes an agent from an account.

Allowed for

  • Administrator

Parameters

NameTypeInRequiredDescription
agent_idintegerPathtrueThe ID of the agent

Code Samples

curl
curl https://www.zopim.com/api/v2/agents/{agent_id} \  -v -H "Authorization: Bearer {token}" -X DELETE
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://www.zopim.com/api/v2/agents/1"	method := "DELETE"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	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://www.zopim.com/api/v2/agents/1")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("DELETE", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'DELETE',  url: 'https://www.zopim.com/api/v2/agents/1',  headers: {	'Content-Type': 'application/json',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://www.zopim.com/api/v2/agents/1"headers = {	"Content-Type": "application/json",}
response = requests.request(	"DELETE",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://www.zopim.com/api/v2/agents/1")request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")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

Delete Shortcuts By Agent ID

  • DELETE /api/v2/agents/{agent_id}/shortcuts

Deletes an agent's shortcuts by their ID.

Warning: Deleted shortcuts are not recoverable.

Allowed for

  • Administrator

Parameters

NameTypeInRequiredDescription
agent_idintegerPathtrueThe ID of the agent

Code Samples

curl
curl https://www.zopim.com/api/v2/agents/{agent_id}/shortcuts \  -v -H "Authorization: Bearer {token}" -X DELETE
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://www.zopim.com/api/v2/agents/1/shortcuts"	method := "DELETE"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")
	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://www.zopim.com/api/v2/agents/1/shortcuts")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("DELETE", null)		.addHeader("Content-Type", "application/json")		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'DELETE',  url: 'https://www.zopim.com/api/v2/agents/1/shortcuts',  headers: {	'Content-Type': 'application/json',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://www.zopim.com/api/v2/agents/1/shortcuts"headers = {	"Content-Type": "application/json",}
response = requests.request(	"DELETE",	url,	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://www.zopim.com/api/v2/agents/1/shortcuts")request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")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