Querying agent availability

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

Parameters

The endpoint accepts the following query string parameters:

`availability`

Type	Required	Example

Type	Required	Example
String	True	`readyForPhoneCall`

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`

Type	Required	Example

Type	Required	Example
String	false	`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`

Type	Required	Example

Type	Required	Example
String	false	`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"
}