Querying agent availability

Owned by Helen Griffith
Last updated: Jul 29, 2024
2 min read

The GET v0/{accountKey}/agents/ endpoint can ascertain the current state of an agent in one or more groups they are a member of. You can also use it to provide a count of available agents, using the field=count parameter, if agent specifics are not required.

In this page


Most URLs in the example code use the following values:

  • ***. To access the API for your region, replace *** with the correct subdomain for your region:
    RegionURL subdomainBase URL
    EMEAemeahttps://emea.cc.vonage.com
    USAnamhttps://nam.cc.vonage.com
    APACapachttps://apac.cc.vonage.com
  • a1b2c3d4e5. The value represents the Vonage Contact Center account on which the API request is run. To run the API request on your account data, you must replace a1b2c3d4e5, where used, with your account's API key. For example, if your API key is mtovfiliti3, use mtovfiliti3 in place of a1b2c3d4e5.
  • <ACCESS_TOKEN>. The value represents a bearer access token which you must use to validate every request. Replace <ACCESS_TOKEN> where used with your bearer access token. For information about getting a bearer access token, see Getting a bearer access token.

Parameters

The endpoint accepts the following query string parameters:

availability

TypeRequiredExample
StringTruereadyForPhoneCall

Determines agent availability to take a call, if no agents are available a count of 0 is returned. The following values are valid: readyForPhoneCall

groups

TypeRequiredExample
Stringfalse 124,654,002(Encoded: 124%2C654%2C002)

Filter response to return only those agents within the specified groups. Expects a URL encoded comma separated list (CSV).

fields

TypeRequiredExample
Stringfalse count

Filters the response data to only return the fields of interest. The following values are valid: count

Use count when you don't need agent related data.

Request/Response Examples

All agents available for taking a phone call

curl -X GET "https://***.cc.vonage.com/v0/a1b2c3d4e5/agents/?availability=readyForPhoneCall" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json"

Returns HTTP status code of 200, containing the following message.

{
    "count": 3,
    "agents": [
        {
            "id": "5464",
            "links": []
        },
        {
            "id": "67668",
            "links": []
        },
        {
            "id": "67697",
            "links": []
        }
    ]
}

Count of all agents available for taking a phone call

curl -X GET "https://***.cc.vonage.com/v0/a1b2c3d4e5/agents/?availability=readyForPhoneCall&fields=count" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json"

Returns HTTP status code of 200, containing the following message.

{
    "count": 3
}

All agents in groups "1111" and "9999" available for taking a phone call

curl -X GET "https://***.cc.vonage.com/v0/a1b2c3d4e5/agents/?availability=readyForPhoneCall&groups=1111%2C9999" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json"


The groups parameter is URL encoded.

Returns HTTP status code of 200, containing the following message.

{
    "count": 2,
    "agents": [
        {
            "id": "5464",
            "links": []
        },
        {
            "id": "67668",
            "links": []
        }
    ]
}

An error occurred due to the request

curl -X GET "https://***.cc.vonage.com/v0/a1b2c3d4e5/agents/?availability=readyForPhoneCall&groups=abc" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json"

Returns HTTP status code of 400, containing a message in a similar format to:

{
    "message": "'groups=abc' contains non-numerical data, groups should consist of only digits"
}