Retrieving outbound call statistics

Deprecated API

The Statistics API was deprecated in Spring '20. For information about migrating to the Insights Stats API, see Migrating from V0 Statistics to the Insights Stats API.

You must be authenticated to run this method. For information on authentication, see V0 - Authentication API.

All requests to this API are required to be cached by clients for 12 minutes (720 seconds) using the Cache-Control header.

Request Scheme

HTTPS

Request Uri

GET v{v#}/{accountKey}/statistics/outboundcalls

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'PD:_ExcerptAPIHeadersVersion2'.

Parameters

You must provide one of either interval or latest, or both start and end.

start

Defines the start of a range that restricts statistics to a time period. Format is in a specific subset of ISO8601 YYYY-MM-DDThh:mm:ssZ. For example, December 10th 2013 15:00:20 is 2013-12-10T15:00:20Z. You must use the 'Z' suffix to indicate UTC time. The caller must translate local time to UTC. Fractional seconds may be accepted, but sub-second accuracy of filtering should not be expected. The maximum period that you can request in a single call is 25 hours.

end

Defines the start of a range that restricts statistics to a time period. The format matches that required for the start parameter.

interval

Decimal time period (in minutes). Used to retrieve statistics for the past number of minutes. Must be greater than 0 and not
more than 1440 minutes (1 day).

latest

Only supported value is "true". Use this to indicate if you want the past 30 minutes worth of statistics returned

additionalfield

Optional parameter. Only supported value is "uniqueid". Including this parameter in the request will cause the response to include a field named "uniqueId" for each call returned. This field will contain a string value which uniquely identifies each event for this call.

Examples

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:
Region URL subdomain Base URL
EMEA emea https://emea.newvoicemedia.com
USA nam https://nam.newvoicemedia.com
APAC apac https://apac.newvoicemedia.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.

All outbound call statistics for a specified date range

curl -X GET "https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/outboundcalls?start=2014-02-10T15:00:00Z&end=2014-02-11T07:15:00Z" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"

Returns HTTP status code of 200

All the latest outbound call statistics

curl -X GET "https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/outboundcalls?latest=true" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"

Returns HTTP status code of 200

All the outbound call statistics for the past 50 minutes

curl -X GET "https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/outboundcalls?interval=50" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"

Returns HTTP status code of 200

All the latest outbound call statistics including unique IDs

curl -X GET "https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/outboundcalls?latest=true&additionalfield=uniqueid" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"

Returns HTTP status code of 200

Example responses

Standard response:

Returns HTTP status code of 200 and headers of:

Cache-Control: must-revalidate, max-age=720, private
Content-Type: application/json; charset=utf-8
Vary: Accept,Authorization

Standard response

{
  "count":1,
  "calls":[
  {
    "callGuid":"01442b58-7f7c-b738-320a-e7346894ac21",
    "callStartedAt":"2014-02-13T13:03:45Z",
    "state":"Make Call State: Agent Failed",
    "agentId":"44215",
    "ringDuration":"00:00:08",
    "duration":"00:02:32"
  }]
}

Response with unique ID:

Returns HTTP status code of 200 and headers of:

Cache-Control: must-revalidate, max-age=720, private
Content-Type: application/json; charset=utf-8
Vary: Accept,Authorization,User-Agent,Accept-Encoding

Response with uniqueId

{
  "count": 1,
  "calls": [
    {
      "callGuid": "0151a0e7-c611-0f1b-b029-61e836844484",
      "callStartedAt": "2015-12-14T14:32:14Z",
      "state": "Make Call State: Other Fail",
      "agentId": "4",
      "destination": "01234567890",
      "ringDuration": "00:00:01",
      "duration": "00:00:00",
      "uniqueId": "D961A806BBBC928086F5734B6732CFF6"
    }
  ]
}

Example: Invalid requests

Version not specified

curl -X GET "https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/outboundcalls?interval=9999" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json"

Returns HTTP status code of 404.

An invalid interval was used

curl -X GET "https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/outboundcalls?interval=9999" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"

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

Minute interval supplied exceeds 1 day or is less than 0

An invalid date format was used

curl -X GET "https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/outboundcalls?start=2014-02-10 23:15:00" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"

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

{
 "message": "The request is invalid."
}

Response values

Property	Description	Additional information
callGuid	The unique identifier (global) of the interaction.
callStartedAt	The date and time of the interaction.	This is a UTC value presented in the ISO 8601 format YYYY-MM-DDThh:mm:ssZ.
state	The resultant state of the interaction.	Possible states: Make Call State: Init Error Make Call State: Agent Fail Make Call State: Other Fail Make Call State: Connect
agentId	The ID of the agent initiating the outbound interaction.
destination	The dialed telephone number or the ID of dialed agent.
ringDuration	The duration of ringing before the interaction connected to the target agent or number, in the format hh:mm:ss.
duration	The total duration of the interaction, in the format hh:mm:ss.
uniqueId	A unique alphanumeric identifier for each individual event that is returned.	This unique ID is only returned if specifically requested.

Region	URL subdomain	Base URL
EMEA	emea	https://emea.newvoicemedia.com
USA	nam	https://nam.newvoicemedia.com
APAC	apac	https://apac.newvoicemedia.com