Agent Availabilities

An agent's availability includes their status, the work items assigned to them, and their maximum capacity per channel.

JSON format

Agent Availabilities are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
attributes	object	false	true	Agent Availability Attributes.
id	string	false	true	The agent's JSON:API ID.
links	object	false	true	A link to the agent's availability.
relationships	object	false	false	A relationships object containing the key channels, whose values refer to channel resources.
type	string	false	true	The JSON:API type agent_availabilities.

The response is a compound document. For each channel, a resource of type channels will be included, and will refer to the first page of work items associated with the channel. These work item resources (of type work_items) will also be included in the response. To request the next or previous page of work items for a channel, use the pagination links provided. Work items are sorted by the time at which they were added, and are returned in chronological order.

Example

{
  "attributes": {
    "agent_id": 10011,
    "agent_status": {
      "id": 1,
      "name": "online",
      "reason": "UNKNOWN",
      "updated_at": "2022-06-21T10:23:25.583732Z"
    },
    "group_ids": [
      1
    ],
    "skills": [
      {
        "id": "1ae11c11-9993-49f8-9850-c2dc096badd1"
      }
    ],
    "version": 236
  },
  "id": "agent_availabilities|10011",
  "links": {
    "self": "https://example.zendesk.com/api/v2/agent_availabilities/10011"
  },
  "relationships": {
    "channels": {
      "data": [
        {
          "id": "agent_availabilities|10011|channels|messaging",
          "type": "channels"
        },
        {
          "id": "agent_availabilities|10011|channels|talk",
          "type": "channels"
        }
      ]
    }
  },
  "type": "agent_availabilities"
}

Get an agent's availability

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

Returns a specified agent's availability.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
agent_id	integer	Path	true	The agent's Zendesk ID.

Code Samples

Curl

curl -v -u {email_address}:{password} \
  'https://example.zendesk.com/api/v2/agent_availabilities/10011'

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/agent_availabilities/10011"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Accept", "application/json")
	req.Header.Add("Zendesk-Api-Version", "2023-02-01")
	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://support.zendesk.com/api/v2/agent_availabilities/10011")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Accept", "application/json")
		.addHeader("Zendesk-Api-Version", "2023-02-01")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/v2/agent_availabilities/10011',
  headers: {
	'Accept': 'application/json',
	'Zendesk-Api-Version': '2023-02-01',
	'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://support.zendesk.com/api/v2/agent_availabilities/10011"
headers = {
	"Accept": "application/json",
	"Zendesk-Api-Version": "2023-02-01",
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/v2/agent_availabilities/10011")
request = Net::HTTP::Get.new(uri, "Accept": "application/json", "Zendesk-Api-Version": "2023-02-01", "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

{
  "data": {
    "attributes": {
      "agent_id": 10011,
      "agent_status": {
        "id": 1,
        "name": "online",
        "reason": "UNKNOWN",
        "updated_at": "2022-06-21T10:23:25.583732Z"
      },
      "group_ids": [
        1
      ],
      "skills": [
        {
          "id": "1ae11c11-9993-49f8-9850-c2dc096badd1"
        }
      ],
      "version": 236
    },
    "id": "agent_availabilities|10011",
    "links": {
      "self": "https://example.zendesk.com/api/v2/agent_availabilities/10011"
    },
    "relationships": {
      "channels": {
        "data": [
          {
            "id": "agent_availabilities|10011|channels|messaging",
            "type": "channels"
          },
          {
            "id": "agent_availabilities|10011|channels|talk",
            "type": "channels"
          }
        ]
      }
    },
    "type": "agent_availabilities"
  },
  "included": [
    {
      "attributes": {
        "max_capacity": 1,
        "name": "messaging",
        "status": "online",
        "updated_at": "2022-06-21T10:23:25.583732Z",
        "work_item_count": 5
      },
      "id": "agent_availabilities|10011|channels|messaging",
      "relationships": {
        "work_items": {
          "data": [
            {
              "id": "agent_availabilities|10011|channels|messaging|work_items|201",
              "type": "work_items"
            },
            {
              "id": "agent_availabilities|10011|channels|messaging|work_items|202",
              "type": "work_items"
            },
            {
              "id": "agent_availabilities|10011|channels|messaging|work_items|203",
              "type": "work_items"
            }
          ],
          "links": {
            "next": "https://example.zendesk.com/api/v2/agent_availabilities/10011/channels/messaging/relationships/work_items?page%5Bafter%5D=203"
          },
          "meta": {
            "has_more": true
          }
        }
      },
      "type": "channels"
    },
    {
      "attributes": {
        "max_capacity": 2,
        "name": "talk",
        "status": "online",
        "updated_at": "2022-06-21T10:23:42.260756Z",
        "work_item_count": 1
      },
      "id": "agent_availabilities|10011|channels|talk",
      "relationships": {
        "work_items": {
          "data": [
            {
              "id": "agent_availabilities|10011|channels|talk|work_items|301",
              "type": "work_items"
            }
          ],
          "links": {},
          "meta": {
            "has_more": false
          }
        }
      },
      "type": "channels"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:20:44.798006Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|messaging|work_items|201",
      "type": "work_items"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:20:57.928097Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|messaging|work_items|202",
      "type": "work_items"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:21:10.778364Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|messaging|work_items|203",
      "type": "work_items"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:21:25.609509Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|talk|work_items|301",
      "type": "work_items"
    }
  ]
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "InvalidParameter",
      "detail": "agent_id must be a positive long integer",
      "source": {
        "parameter": "agent_id"
      },
      "title": "Bad Request"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "InvalidCredentials",
      "title": "Unauthorized"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "InvalidPermissions",
      "title": "Forbidden"
    }
  ]
}

404 Not Found

// Status 404 Not Found

{
  "errors": [
    {
      "code": "AgentNotFound",
      "detail": "Agent not found",
      "source": {
        "parameter": "agent_id"
      },
      "title": "Not Found"
    }
  ]
}

406 Not Acceptable

// Status 406 Not Acceptable

{
  "errors": [
    {
      "code": "NotAcceptable",
      "title": "Not Acceptable"
    }
  ]
}

429 Too Many Requests

// Status 429 Too Many Requests

{
  "errors": [
    {
      "code": "TooManyRequests",
      "title": "Too Many Requests"
    }
  ]
}

500 Internal Server Error

// Status 500 Internal Server Error

{
  "errors": [
    {
      "code": "InternalServerError",
      "title": "Internal server error"
    }
  ]
}

Get agent availabilities

• GET /api/v2/agent_availabilities

With no query parameters, requests the availabilities of all agents associated with the account. Parameters can be used to filter by channel status (e.g. filter[channel_status]=messaging:online) and/or work item counts (e.g. filter[work_items_count]=messaging:3) in specified channels, and/or remaining capacity (e.g. filter[remaining_capacity]=messaging:3) in specified channels, as well as agent status IDs (e.g. filter[agent_status_id]=1), agent status names (e.g. filter[agent_status_name]="online"), group ids (e.g. filter[group_id]=6443772435837), and skill ids (e.g. filter[skill]=93629b66-ee25-4c7a-af44-8d622958efd3).

When filter[work_items_count] is used, the query will return agents with a number of work items less than or equal to the number specified.

When filter[remaining_capacity] is used, the query will return agents with a remaining capacity greater than or equal to the number specified.

Agent status filters are combined with logical OR. States for the same channel are also combined with logical OR. Filters are then combined with logical AND.

For example, with the query parameters ?filter[channel_status]=messaging:online,talk:online&filter[work_items_count]=messaging:1,talk:1&filter[remaining_capacity]=messaging:1&filter[agent_status_name]="online","offline"&filter[group_id]=6443772435837,7751066484861, the request will return agents who are online for both Messaging and Talk, who have at least one work item assigned to them for each of those channels, who have at least capacity for one or more messaging work items, whose agent status is online or offline and who are part of group with id 6443772435837 or 7751066484861.

To return channel-specific data for only one channel, submit the channel name as the value of the query parameter select_channel.

Agent availabilities are returned in an implementation-dependent order and are paginated. To navigate to the next or previous page of results, use the pagination links provided, which use the page[before] and page[after] parameters.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
filter[agent_id]	string	Query	false	A filter whose value is a comma-separated list of agent IDs.
filter[agent_status_id]	string	Query	false	A filter whose list is a comma-separated list of agent status IDs.
filter[agent_status_name]	string	Query	false	A filter whose value is a comma-separated list of agent status names, each one enclosed in double quotes ("). A backslash (\) can be used to escape a double quote or a literal backslash in an agent status name.
filter[channel_status]	string	Query	false	A filter whose value is a comma-separated list of elements in the format channel:status.
filter[group_id]	string	Query	false	A filter whose value is a comma-separated list of group IDs.
filter[remaining_capacity]	string	Query	false	A filter whose value is a comma-separated list of elements in the format channel:remainingCapacity.
filter[skill]	string	Query	false	A filter whose value is a comma-separated list of skill IDs.
filter[work_items_count]	string	Query	false	A filter whose value is a comma-separated list of elements in the format channel:workItemsCount.
page[after]	string	Query	false	The cursor returned in the next link in the preceding response.
page[before]	string	Query	false	The cursor returned in the prev link in the preceding response.
page[size]	integer	Query	false	The maximum number of agent availabilities to be returned.
select_channel	string	Query	false	If provided, the response will include channel-specific data only for the specified channel.

Code Samples

Curl

curl -v -u {email_address}:{password} \
  'https://example.zendesk.com/api/v2/agent_availabilities?filter[channel_status]=messaging:online&filter[work_items_count]=messaging:1&filter[remaining_capacity]=messaging:1&filter[channel_status]=talk:online&filter[work_items_count]=talk:1&filter[group_id]=1,2'

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/agent_availabilities?filter[agent_id]=6141658332961986144%2C126964444658584641&filter[agent_status_id]=123%2C134&filter[agent_status_name]=%5C%22online%5C%22%2C%5C%22meeting%5C&filter[channel_status]=messaging%3Aonline%2Csupport%3Aonline&filter[group_id]=1%2C2&filter[remaining_capacity]=messaging%3A3%2Csupport%3A2&filter[skill]=93629b66-ee25-4c7a-af44-8d622958efd3%2C1ae11c11-9993-49f8-9850-c2dc096badd1&filter[work_items_count]=messaging%3A3%2Csupport%3A2&page[after]=10011_0&page[before]=10011_0&page[size]=20&select_channel=messaging"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Accept", "application/json")
	req.Header.Add("Zendesk-Api-Version", "2023-02-01")
	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://support.zendesk.com/api/v2/agent_availabilities")
		.newBuilder()
		.addQueryParameter("filter[agent_id]", "6141658332961986144,126964444658584641")
		.addQueryParameter("filter[agent_status_id]", "123,134")
		.addQueryParameter("filter[agent_status_name]", "\"online\",\"meeting\")
		.addQueryParameter("filter[channel_status]", "messaging:online,support:online")
		.addQueryParameter("filter[group_id]", "1,2")
		.addQueryParameter("filter[remaining_capacity]", "messaging:3,support:2")
		.addQueryParameter("filter[skill]", "93629b66-ee25-4c7a-af44-8d622958efd3,1ae11c11-9993-49f8-9850-c2dc096badd1")
		.addQueryParameter("filter[work_items_count]", "messaging:3,support:2")
		.addQueryParameter("page[after]", "10011_0")
		.addQueryParameter("page[before]", "10011_0")
		.addQueryParameter("page[size]", "20")
		.addQueryParameter("select_channel", "messaging");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Accept", "application/json")
		.addHeader("Zendesk-Api-Version", "2023-02-01")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/v2/agent_availabilities',
  headers: {
	'Accept': 'application/json',
	'Zendesk-Api-Version': '2023-02-01',
	'Content-Type': 'application/json',
  },
  params: {
    'filter[agent_id]': '6141658332961986144%2C126964444658584641',
    'filter[agent_status_id]': '123%2C134',
    'filter[agent_status_name]': '%5C%22online%5C%22%2C%5C%22meeting%5C',
    'filter[channel_status]': 'messaging%3Aonline%2Csupport%3Aonline',
    'filter[group_id]': '1%2C2',
    'filter[remaining_capacity]': 'messaging%3A3%2Csupport%3A2',
    'filter[skill]': '93629b66-ee25-4c7a-af44-8d622958efd3%2C1ae11c11-9993-49f8-9850-c2dc096badd1',
    'filter[work_items_count]': 'messaging%3A3%2Csupport%3A2',
    'page[after]': '10011_0',
    'page[before]': '10011_0',
    'page[size]': '20',
    'select_channel': 'messaging',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/v2/agent_availabilities?filter[agent_id]=6141658332961986144%2C126964444658584641&filter[agent_status_id]=123%2C134&filter[agent_status_name]=%5C%22online%5C%22%2C%5C%22meeting%5C&filter[channel_status]=messaging%3Aonline%2Csupport%3Aonline&filter[group_id]=1%2C2&filter[remaining_capacity]=messaging%3A3%2Csupport%3A2&filter[skill]=93629b66-ee25-4c7a-af44-8d622958efd3%2C1ae11c11-9993-49f8-9850-c2dc096badd1&filter[work_items_count]=messaging%3A3%2Csupport%3A2&page[after]=10011_0&page[before]=10011_0&page[size]=20&select_channel=messaging"
headers = {
	"Accept": "application/json",
	"Zendesk-Api-Version": "2023-02-01",
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/v2/agent_availabilities")
uri.query = URI.encode_www_form("filter[agent_id]": "6141658332961986144,126964444658584641", "filter[agent_status_id]": "123,134", "filter[agent_status_name]": "\"online\",\"meeting\", "filter[channel_status]": "messaging:online,support:online", "filter[group_id]": "1,2", "filter[remaining_capacity]": "messaging:3,support:2", "filter[skill]": "93629b66-ee25-4c7a-af44-8d622958efd3,1ae11c11-9993-49f8-9850-c2dc096badd1", "filter[work_items_count]": "messaging:3,support:2", "page[after]": "10011_0", "page[before]": "10011_0", "page[size]": "20", "select_channel": "messaging")
request = Net::HTTP::Get.new(uri, "Accept": "application/json", "Zendesk-Api-Version": "2023-02-01", "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

{
  "data": [
    {
      "attributes": {
        "agent_id": 10011,
        "agent_status": {
          "id": 1,
          "name": "online",
          "reason": "UNKNOWN",
          "updated_at": "2022-06-21T10:23:25.583732Z"
        },
        "group_ids": [
          1
        ],
        "skills": [
          {
            "id": "1ae11c11-9993-49f8-9850-c2dc096badd1"
          }
        ],
        "version": 236
      },
      "id": "agent_availabilities|10011",
      "links": {
        "self": "https://example.zendesk.com/api/v2/agent_availabilities/10011"
      },
      "relationships": {
        "channels": {
          "data": [
            {
              "id": "agent_availabilities|10011|channels|messaging",
              "type": "channels"
            },
            {
              "id": "agent_availabilities|10011|channels|talk",
              "type": "channels"
            }
          ]
        }
      },
      "type": "agent_availabilities"
    },
    {
      "attributes": {
        "agent_id": 10012,
        "agent_status": {
          "id": 1,
          "name": "online",
          "reason": "UNKNOWN",
          "updated_at": "2022-06-21T10:23:25.583732Z"
        },
        "group_ids": [
          2
        ],
        "skills": [
          {
            "id": "1ae11c11-9993-49f8-9850-c2dc096badd1"
          }
        ],
        "version": 875
      },
      "id": "agent_availabilities|10012",
      "links": {
        "self": "https://example.zendesk.com/api/v2/agent_availabilities/10012"
      },
      "relationships": {
        "channels": {
          "data": [
            {
              "id": "agent_availabilities|10012|channels|messaging",
              "type": "channels"
            },
            {
              "id": "agent_availabilities|10012|channels|talk",
              "type": "channels"
            }
          ]
        }
      },
      "type": "agent_availabilities"
    }
  ],
  "included": [
    {
      "attributes": {
        "max_capacity": 1,
        "name": "messaging",
        "status": "online",
        "updated_at": "2022-06-21T10:23:25.583732Z",
        "work_item_count": 5
      },
      "id": "agent_availabilities|10011|channels|messaging",
      "relationships": {
        "work_items": {
          "data": [
            {
              "id": "agent_availabilities|10011|channels|messaging|work_items|201",
              "type": "work_items"
            },
            {
              "id": "agent_availabilities|10011|channels|messaging|work_items|202",
              "type": "work_items"
            },
            {
              "id": "agent_availabilities|10011|channels|messaging|work_items|203",
              "type": "work_items"
            }
          ],
          "links": {
            "next": "https://example.zendesk.com/api/v2/agent_availabilities/10011/channels/messaging/relationships/work_items?page%5Bafter%5D=203"
          },
          "meta": {
            "has_more": true
          }
        }
      },
      "type": "channels"
    },
    {
      "attributes": {
        "max_capacity": 2,
        "name": "talk",
        "status": "online",
        "updated_at": "2022-06-21T10:23:42.260756Z",
        "work_item_count": 1
      },
      "id": "agent_availabilities|10011|channels|talk",
      "relationships": {
        "work_items": {
          "data": [
            {
              "id": "agent_availabilities|10011|channels|talk|work_items|301",
              "type": "work_items"
            }
          ],
          "links": {},
          "meta": {
            "has_more": false
          }
        }
      },
      "type": "channels"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:20:44.798006Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|messaging|work_items|201",
      "type": "work_items"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:20:57.928097Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|messaging|work_items|202",
      "type": "work_items"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:21:10.778364Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|messaging|work_items|203",
      "type": "work_items"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:21:25.609509Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|talk|work_items|301",
      "type": "work_items"
    },
    {
      "attributes": {
        "max_capacity": 2,
        "name": "messaging",
        "status": "online",
        "updated_at": "2022-07-27T16:06:52.344273Z",
        "work_item_count": 1
      },
      "id": "agent_availabilities|10012|channels|messaging",
      "relationships": {
        "work_items": {
          "data": [
            {
              "id": "agent_availabilities|10012|channels|messaging|work_items|401",
              "type": "work_items"
            }
          ],
          "links": {},
          "meta": {
            "has_more": false
          }
        }
      },
      "type": "channels"
    },
    {
      "attributes": {
        "max_capacity": 1,
        "name": "talk",
        "status": "online",
        "updated_at": "2022-07-27T16:04:49.119790Z",
        "work_item_count": 1
      },
      "id": "agent_availabilities|10012|channels|talk",
      "relationships": {
        "work_items": {
          "data": [
            {
              "id": "agent_availabilities|10012|channels|talk|work_items|501",
              "type": "work_items"
            }
          ],
          "links": {},
          "meta": {
            "has_more": false
          }
        }
      },
      "type": "channels"
    },
    {
      "attributes": {
        "added_at": "2022-07-27T16:06:26.762432Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10012|channels|messaging|work_items|401",
      "type": "work_items"
    },
    {
      "attributes": {
        "added_at": "2022-07-27T15:59:20.849756Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10012|channels|talk|work_items|501",
      "type": "work_items"
    }
  ],
  "links": {
    "next": "https://example.zendesk.com/api/v2/agent_availabilities?page%5Bafter%5D=10012_0",
    "prev": "https://example.zendesk.com/api/v2/agent_availabilities?page%5Bbefore%5D=10011_0"
  },
  "meta": {
    "has_more": true
  }
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "InvalidParameter",
      "detail": "agent_id must be a positive long integer",
      "source": {
        "parameter": "agent_id"
      },
      "title": "Bad Request"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "InvalidCredentials",
      "title": "Unauthorized"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "InvalidPermissions",
      "title": "Forbidden"
    }
  ]
}

404 Not Found

// Status 404 Not Found

{
  "errors": [
    {
      "code": "AgentNotFound",
      "detail": "Agent not found",
      "source": {
        "parameter": "agent_id"
      },
      "title": "Not Found"
    }
  ]
}

406 Not Acceptable

// Status 406 Not Acceptable

{
  "errors": [
    {
      "code": "NotAcceptable",
      "title": "Not Acceptable"
    }
  ]
}

429 Too Many Requests

// Status 429 Too Many Requests

{
  "errors": [
    {
      "code": "TooManyRequests",
      "title": "Too Many Requests"
    }
  ]
}

500 Internal Server Error

// Status 500 Internal Server Error

{
  "errors": [
    {
      "code": "InternalServerError",
      "title": "Internal server error"
    }
  ]
}

Get an agent's assigned work items

• GET /api/v2/agent_availabilities/{agent_id}/channels/{channel}/relationships/work_items

With no query parameters, returns the first page of work items assigned to the agent for the specified channel. To navigate to the next or previous page of work items, use the pagination links provided, which use the page[before] and page[after] parameters.

Work items are sorted by the time at which they were added, and are returned in chronological order by default. To return them in reverse chronological order, use the parameter sort=-added_at.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
page[after]	string	Query	false	The cursor returned in the next link in the preceding response.
page[before]	string	Query	false	The cursor returned in the prev link in the preceding response.
page[size]	integer	Query	false	The maximum number of work items to be returned.
sort	string	Query	false	The sort order for work items (added_at for chronological order or -added_at for reverse chronological order, default added_at).
agent_id	integer	Path	true	The agent's Zendesk ID.
channel	string	Path	true	The channel name.

Code Samples

Curl

curl -v -u {email_address}:{password} \
  'https://example.zendesk.com/api/v2/agent_availabilities/10011/channels/talk/relationships/work_items?page%5Bafter%5D=203&sort=added_at'

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/agent_availabilities/10011/channels/messaging/relationships/work_items?page[after]=9ed76ce4-577d-435c-8402-755f7d401ced&page[before]=9ed76ce4-577d-435c-8402-755f7d401ced&page[size]=20&sort=-added_at"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Accept", "application/json")
	req.Header.Add("Zendesk-Api-Version", "2023-02-01")
	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://support.zendesk.com/api/v2/agent_availabilities/10011/channels/messaging/relationships/work_items")
		.newBuilder()
		.addQueryParameter("page[after]", "9ed76ce4-577d-435c-8402-755f7d401ced")
		.addQueryParameter("page[before]", "9ed76ce4-577d-435c-8402-755f7d401ced")
		.addQueryParameter("page[size]", "20")
		.addQueryParameter("sort", "-added_at");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Accept", "application/json")
		.addHeader("Zendesk-Api-Version", "2023-02-01")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/v2/agent_availabilities/10011/channels/messaging/relationships/work_items',
  headers: {
	'Accept': 'application/json',
	'Zendesk-Api-Version': '2023-02-01',
	'Content-Type': 'application/json',
  },
  params: {
    'page[after]': '9ed76ce4-577d-435c-8402-755f7d401ced',
    'page[before]': '9ed76ce4-577d-435c-8402-755f7d401ced',
    'page[size]': '20',
    'sort': '-added_at',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/v2/agent_availabilities/10011/channels/messaging/relationships/work_items?page[after]=9ed76ce4-577d-435c-8402-755f7d401ced&page[before]=9ed76ce4-577d-435c-8402-755f7d401ced&page[size]=20&sort=-added_at"
headers = {
	"Accept": "application/json",
	"Zendesk-Api-Version": "2023-02-01",
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/v2/agent_availabilities/10011/channels/messaging/relationships/work_items")
uri.query = URI.encode_www_form("page[after]": "9ed76ce4-577d-435c-8402-755f7d401ced", "page[before]": "9ed76ce4-577d-435c-8402-755f7d401ced", "page[size]": "20", "sort": "-added_at")
request = Net::HTTP::Get.new(uri, "Accept": "application/json", "Zendesk-Api-Version": "2023-02-01", "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

{
  "data": [
    {
      "id": "agent_availabilities|10011|channels|messaging|work_items|202",
      "type": "work_items"
    },
    {
      "id": "agent_availabilities|10011|channels|messaging|work_items|203",
      "type": "work_items"
    }
  ],
  "included": [
    {
      "attributes": {
        "added_at": "2022-06-21T10:21:58.636732Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|messaging|work_items|202",
      "type": "work_items"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:22:18.484395Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|messaging|work_items|203",
      "type": "work_items"
    }
  ],
  "links": {
    "next": "https://example.zendesk.com/api/v2/agent_availabilities/10011/channels/messaging/relationships/work_items?page%5Bafter%5D=203",
    "prev": "https://example.zendesk.com/api/v2/agent_availabilities/10011/channels/messaging/relationships/work_items?page%5Bbefore%5D=202"
  },
  "meta": {
    "has_more": true
  }
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "InvalidParameter",
      "detail": "agent_id must be a positive long integer",
      "source": {
        "parameter": "agent_id"
      },
      "title": "Bad Request"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "InvalidCredentials",
      "title": "Unauthorized"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "InvalidPermissions",
      "title": "Forbidden"
    }
  ]
}

404 Not Found

// Status 404 Not Found

{
  "errors": [
    {
      "code": "AgentNotFound",
      "detail": "Agent not found",
      "source": {
        "parameter": "agent_id"
      },
      "title": "Not Found"
    }
  ]
}

406 Not Acceptable

// Status 406 Not Acceptable

{
  "errors": [
    {
      "code": "NotAcceptable",
      "title": "Not Acceptable"
    }
  ]
}

429 Too Many Requests

// Status 429 Too Many Requests

{
  "errors": [
    {
      "code": "TooManyRequests",
      "title": "Too Many Requests"
    }
  ]
}

500 Internal Server Error

// Status 500 Internal Server Error

{
  "errors": [
    {
      "code": "InternalServerError",
      "title": "Internal server error"
    }
  ]
}

Get my availability

• GET /api/v2/agent_availabilities/me

Returns the requesting agent's availability.

Allowed For

• Admins
• Agents

Code Samples

Curl

curl -v -u {email_address}:{password} \
  'https://example.zendesk.com/api/v2/agent_availabilities/me'

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/agent_availabilities/me"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Accept", "application/json")
	req.Header.Add("Zendesk-Api-Version", "2023-02-01")
	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://support.zendesk.com/api/v2/agent_availabilities/me")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Accept", "application/json")
		.addHeader("Zendesk-Api-Version", "2023-02-01")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/v2/agent_availabilities/me',
  headers: {
	'Accept': 'application/json',
	'Zendesk-Api-Version': '2023-02-01',
	'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://support.zendesk.com/api/v2/agent_availabilities/me"
headers = {
	"Accept": "application/json",
	"Zendesk-Api-Version": "2023-02-01",
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/v2/agent_availabilities/me")
request = Net::HTTP::Get.new(uri, "Accept": "application/json", "Zendesk-Api-Version": "2023-02-01", "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

{
  "data": {
    "attributes": {
      "agent_id": 10011,
      "agent_status": {
        "id": 1,
        "name": "online",
        "reason": "UNKNOWN",
        "updated_at": "2022-06-21T10:23:25.583732Z"
      },
      "group_ids": [
        1
      ],
      "skills": [
        {
          "id": "1ae11c11-9993-49f8-9850-c2dc096badd1"
        }
      ],
      "version": 236
    },
    "id": "agent_availabilities|10011",
    "links": {
      "self": "https://example.zendesk.com/api/v2/agent_availabilities/me"
    },
    "relationships": {
      "channels": {
        "data": [
          {
            "id": "agent_availabilities|10011|channels|messaging",
            "type": "channels"
          },
          {
            "id": "agent_availabilities|10011|channels|talk",
            "type": "channels"
          }
        ]
      }
    },
    "type": "agent_availabilities"
  },
  "included": [
    {
      "attributes": {
        "max_capacity": 1,
        "name": "messaging",
        "status": "online",
        "updated_at": "2022-06-21T10:23:25.583732Z",
        "work_item_count": 5
      },
      "id": "agent_availabilities|10011|channels|messaging",
      "relationships": {
        "work_items": {
          "data": [
            {
              "id": "agent_availabilities|10011|channels|messaging|work_items|201",
              "type": "work_items"
            },
            {
              "id": "agent_availabilities|10011|channels|messaging|work_items|202",
              "type": "work_items"
            },
            {
              "id": "agent_availabilities|10011|channels|messaging|work_items|203",
              "type": "work_items"
            }
          ],
          "links": {
            "next": "https://example.zendesk.com/api/v2/agent_availabilities/me/channels/messaging/relationships/work_items?page%5Bafter%5D=203"
          },
          "meta": {
            "has_more": true
          }
        }
      },
      "type": "channels"
    },
    {
      "attributes": {
        "max_capacity": 2,
        "name": "talk",
        "status": "online",
        "updated_at": "2022-06-21T10:23:42.260756Z",
        "work_item_count": 1
      },
      "id": "agent_availabilities|10011|channels|talk",
      "relationships": {
        "work_items": {
          "data": [
            {
              "id": "agent_availabilities|10011|channels|talk|work_items|301",
              "type": "work_items"
            }
          ],
          "links": {},
          "meta": {
            "has_more": false
          }
        }
      },
      "type": "channels"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:20:44.798006Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|messaging|work_items|201",
      "type": "work_items"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:20:57.928097Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|messaging|work_items|202",
      "type": "work_items"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:21:10.778364Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|messaging|work_items|203",
      "type": "work_items"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:21:25.609509Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|talk|work_items|301",
      "type": "work_items"
    }
  ]
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "InvalidParameter",
      "detail": "agent_id must be a positive long integer",
      "source": {
        "parameter": "agent_id"
      },
      "title": "Bad Request"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "InvalidCredentials",
      "title": "Unauthorized"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "InvalidPermissions",
      "title": "Forbidden"
    }
  ]
}

404 Not Found

// Status 404 Not Found

{
  "errors": [
    {
      "code": "AgentNotFound",
      "detail": "Agent not found",
      "source": {
        "parameter": "agent_id"
      },
      "title": "Not Found"
    }
  ]
}

406 Not Acceptable

// Status 406 Not Acceptable

{
  "errors": [
    {
      "code": "NotAcceptable",
      "title": "Not Acceptable"
    }
  ]
}

429 Too Many Requests

// Status 429 Too Many Requests

{
  "errors": [
    {
      "code": "TooManyRequests",
      "title": "Too Many Requests"
    }
  ]
}

500 Internal Server Error

// Status 500 Internal Server Error

{
  "errors": [
    {
      "code": "InternalServerError",
      "title": "Internal server error"
    }
  ]
}

Get my work items

• GET /api/v2/agent_availabilities/me/channels/{channel}/relationships/work_items

With no query parameters, returns the first page of work items assigned to the requesting agent for the specified channel. To navigate to the next or previous page of work items, use the pagination links provided, which use the page[before] and page[after] parameters.

Work items are sorted by the time at which they were added, and are returned in chronological order by default. To return them in reverse chronological order, use the parameter sort=-added_at.

Allowed For

• Admins
• Agents

Parameters

Name	Type	In	Required	Description
page[after]	string	Query	false	The cursor returned in the next link in the preceding response.
page[before]	string	Query	false	The cursor returned in the prev link in the preceding response.
page[size]	integer	Query	false	The maximum number of work items to be returned.
sort	string	Query	false	The sort order for work items (added_at for chronological order or -added_at for reverse chronological order, default added_at).
channel	string	Path	true	The channel name.

Code Samples

Curl

curl -v -u {email_address}:{password} \
  'https://example.zendesk.com/api/v2/agent_availabilities/me/channels/talk/relationships/work_items?page%5Bafter%5D=203&sort=added_at'

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://support.zendesk.com/api/v2/agent_availabilities/me/channels/messaging/relationships/work_items?page[after]=9ed76ce4-577d-435c-8402-755f7d401ced&page[before]=9ed76ce4-577d-435c-8402-755f7d401ced&page[size]=20&sort=-added_at"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Accept", "application/json")
	req.Header.Add("Zendesk-Api-Version", "2023-02-01")
	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://support.zendesk.com/api/v2/agent_availabilities/me/channels/messaging/relationships/work_items")
		.newBuilder()
		.addQueryParameter("page[after]", "9ed76ce4-577d-435c-8402-755f7d401ced")
		.addQueryParameter("page[before]", "9ed76ce4-577d-435c-8402-755f7d401ced")
		.addQueryParameter("page[size]", "20")
		.addQueryParameter("sort", "-added_at");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Accept", "application/json")
		.addHeader("Zendesk-Api-Version", "2023-02-01")
		.addHeader("Content-Type", "application/json")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/v2/agent_availabilities/me/channels/messaging/relationships/work_items',
  headers: {
	'Accept': 'application/json',
	'Zendesk-Api-Version': '2023-02-01',
	'Content-Type': 'application/json',
  },
  params: {
    'page[after]': '9ed76ce4-577d-435c-8402-755f7d401ced',
    'page[before]': '9ed76ce4-577d-435c-8402-755f7d401ced',
    'page[size]': '20',
    'sort': '-added_at',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://support.zendesk.com/api/v2/agent_availabilities/me/channels/messaging/relationships/work_items?page[after]=9ed76ce4-577d-435c-8402-755f7d401ced&page[before]=9ed76ce4-577d-435c-8402-755f7d401ced&page[size]=20&sort=-added_at"
headers = {
	"Accept": "application/json",
	"Zendesk-Api-Version": "2023-02-01",
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/v2/agent_availabilities/me/channels/messaging/relationships/work_items")
uri.query = URI.encode_www_form("page[after]": "9ed76ce4-577d-435c-8402-755f7d401ced", "page[before]": "9ed76ce4-577d-435c-8402-755f7d401ced", "page[size]": "20", "sort": "-added_at")
request = Net::HTTP::Get.new(uri, "Accept": "application/json", "Zendesk-Api-Version": "2023-02-01", "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

{
  "data": [
    {
      "id": "agent_availabilities|10011|channels|messaging|work_items|202",
      "type": "work_items"
    },
    {
      "id": "agent_availabilities|10011|channels|messaging|work_items|203",
      "type": "work_items"
    }
  ],
  "included": [
    {
      "attributes": {
        "added_at": "2022-06-21T10:21:58.636732Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|messaging|work_items|202",
      "type": "work_items"
    },
    {
      "attributes": {
        "added_at": "2022-06-21T10:22:18.484395Z",
        "reason": "ASSIGNED"
      },
      "id": "agent_availabilities|10011|channels|messaging|work_items|203",
      "type": "work_items"
    }
  ],
  "links": {
    "next": "https://example.zendesk.com/api/v2/agent_availabilities/me/channels/messaging/relationships/work_items?page%5Bafter%5D=203",
    "prev": "https://example.zendesk.com/api/v2/agent_availabilities/me/channels/messaging/relationships/work_items?page%5Bbefore%5D=202"
  },
  "meta": {
    "has_more": true
  }
}

400 Bad Request

// Status 400 Bad Request

{
  "errors": [
    {
      "code": "InvalidParameter",
      "detail": "agent_id must be a positive long integer",
      "source": {
        "parameter": "agent_id"
      },
      "title": "Bad Request"
    }
  ]
}

401 Unauthorized

// Status 401 Unauthorized

{
  "errors": [
    {
      "code": "InvalidCredentials",
      "title": "Unauthorized"
    }
  ]
}

403 Forbidden

// Status 403 Forbidden

{
  "errors": [
    {
      "code": "InvalidPermissions",
      "title": "Forbidden"
    }
  ]
}

404 Not Found

// Status 404 Not Found

{
  "errors": [
    {
      "code": "AgentNotFound",
      "detail": "Agent not found",
      "source": {
        "parameter": "agent_id"
      },
      "title": "Not Found"
    }
  ]
}

406 Not Acceptable

// Status 406 Not Acceptable

{
  "errors": [
    {
      "code": "NotAcceptable",
      "title": "Not Acceptable"
    }
  ]
}

429 Too Many Requests

// Status 429 Too Many Requests

{
  "errors": [
    {
      "code": "TooManyRequests",
      "title": "Too Many Requests"
    }
  ]
}

500 Internal Server Error

// Status 500 Internal Server Error

{
  "errors": [
    {
      "code": "InternalServerError",
      "title": "Internal server error"
    }
  ]
}