All requests to Insights Stats API endpoints return standard HTTP headers, including the response status code, and a response body in JSON format.
Successful requests return a 200 Success
code with a JSON object in the response body.
Responses from endpoints that can return multiple resources contain a meta
item in the response body. The meta
item appears at the start of the response and contains the following parameters:
page
. The current requested page.count
. The count of the items returned for a specific request. If we have the same or more as the limit the value matches the same value.pageCount
. The number of pages that result from the specified limit.totalCount
. The total number of items that we can retrieve from the API.{ "meta": { "page": 1, "count": 25, "pageCount": 8, "totalCount": 200 }, "items": [ ... ], "upTo": "2019-12-19T14:18:32.395Z" } |
The response body also contains the upTo
parameter. The upTo
parameter appears at the end of the response, and represents the time of the request. This time is useful if you are polling the API as you know exactly when the previous request retrieved data from Vonage Contact Center.
HTTP headers include:
HTTP/1.1 CODE MESSAGE Cache-Control: max-age=5, must-revalidate, private |
The response body contains either the requested information or an error message:
{ "message":"MESSAGE" } |
Errors are returned using standard HTTP error code syntax, such as 400 Bad Request
. Additional information is included in the body of the return call in JSON format, usually in the following format:
{ "message": "Appropriate 400 error message" } |
The Insights Stats API returns 400 Bad Request
in response to an invalid request. You may have provided a DateTime value in the wrong format or a number value outside of the allowed limits.
If you do not provide the required API version in the Accept header, you will receive the following message in addition to the 400 error code:
{ "message": "Version missing from Accept header!" } |
If you provide an invalid API version in the Accept header, you will receive the following message in addition to the 400 error code:
{ "message": "Invalid api-version! Valid values: 1,2" } |
If you do not provide a required value for a parameter, you will receive the following message in addition to the 400 error code:
{ "message": "child \"start\" fails because [\"start\" is required]" } |
If you provide a DateTime value in a parameter in the wrong format, you will receive the following message in addition to the 400 error code:
{ "message": "child \"start\" fails because [\"start\" must be a valid ISO 8601 date]" } |
If you provide an invalid GUID, you will receive the following message in addition to the 400 error code:
{ "message": "child \"guid\" fails because [\"guid\" must be a valid GUID]" } |
The Insights Stats API returns 401 Unauthorized
in response to an invalid, expired or missing bearer access token.
If you do not provide your bearer access token, you will receive the following message in addition to the 401 error code:
{ "error_description": "The access token is missing", "error": "invalid_request" } |
Invalid tokenIf you provide an invalid or expired bearer access token, you will receive the following message in addition to the 401 error code:
{ "error_description": "The access token is invalid or has expired", "error": "invalid_token" } |
If your client credentials contain the required scope, but your bearer access token does not, you will receive the following message in addition to the 401 error code:
{ "message": "Unauthorized" } |
The Insights Stats API returns 403 Forbidden
in response to a request that is not authorized.
If you can authenticate with the API but do not have access to the specific resource you request, you will receive the following message in addition to the 403 error code:
{ "message": "Insufficient scope" } |
The Insights Stats API returns 404 Not Found
in response to a request for an item that was not found. You may have requested an interaction that doesn’t exist.
If you request an item that is not found, you will receive the following message in addition to the 404 error code:
{ "message": "Not Found" } |
The Insights Stats API returns 405 Method Not Allowed
in response to a call to a method that is not allowed. For example a POST method.
If you send a request using a method that is not allowed, you will receive the following message in addition to the 405 error code:
{ "message": "Method Not Allowed" } |
An internal server error occurred.