Requests (Insights Stats API)

Owned by Helen Griffith
Last updated: Oct 12, 2023
12 min read

Request parameters

Path parameters

In requests to some API endpoints you can provide your own values in place of path parameters.

For example, in the GET stats/interactions/{guid} endpoint, you must replace {guid} with the real value for the interaction you require.

Path parameters are required.

Query string parameters

In most API endpoints you can use query string parameters to specify options that limit the data included in responses.

Some query string parameters are required; others are optional.

For example, in the GET /agent-activities endpoint, you must add a start parameter and optionally add an end parameter to the query string:

https://***.api.newvoicemedia.com/stats/agent-activities?start=2017-06-13T13:39:00.000Z&end=2017-06-13T13:41:00.000

Header parameters

All Insights Stats API requests require the following header parameters:

accept

Required The accept header describes the content types that the response can return. The content-type of the Insights Stats API’s responses is always in JSON format so you must set the accept header to accept JSON. You must also specify the version of the API you are using. For information about specifying the version, see Versioning.

Example application/vnd.newvoicemedia.v3+json

authorization

Required To make a request to the Insights Stats API, you must provide your bearer access token in the authorization header.

You get your bearer access token from the Authentication API. For information about getting and using your bearer access token, see How to authenticate with a Vonage Contact Center API.

Request body parameters

Currently Insights Stats API endpoints have only a GET method and therefore do not accept request body parameters.

Max request window

Request time windows are limited to 31 days for endpoints /agent-activities, /interactions, and /wfm/agent-states. If your request exceeds 31 days, the response will contain:

  • a HTTP/1.1 400 status code with the following message:
{
   "message":"Request window size limit exceeded 31 days"
}

Max request size

Requests are limited to 10MB. If your request exceeds 10MB, the response contains either:

  • a HTTP/1.1 413 status code with the following message:
{
    "message":"Payload Too Large"
}

or

  • a HTTP/1.1 417 status code with the following message:
{
   "message":"Request size limit exceeded"
}

Example request

$ curl -X "POST" -i --data "@/largeFile.txt" https://***.api.newvoicemedia.com/stats
HTTP/1.1 100 Continue

Example response

HTTP/1.1 417
Date: Mon, 18 Jul 2016 11:40:01 GMT

Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive

{"message":"Request size limit exceeded"}

Dates and times

Internationalization

Use ISO 8601 formats for DateTimes, for example, 2019-04-23T13:00:35.205Z.

All DateTime values, in both requests and responses, are in Coordinated Universal Time (UTC).

Timespans

Express durations or timespans in integer values of milliseconds, for example, 1200 represents 0.02 minutes.

Pagination

Requests to endpoints that return multiple resources accept two query parameters that are both optional:

  • page. The required page (default is 1).
  • limit. The required size (number of items) per page (current default 2000). Maximum of 5000.

Responses from endpoints that can return multiple resources contain the following metadata:

  • 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.

Usage scenarios

User does not provide any pagination options

Example request

https://***.api.newvoicemedia.com/stats/interactions?start=2019-12-19

The request does not include any of the query parameters for pagination.

Example response

{
  "meta": {
    "page": 1,
    "count": 25,
    "pageCount": 8,
    "totalCount": 200
  },
"items": [
    {
      "status": "Completed",
      "medium": "Phone",
      "mediumManager": "CC",
      "guid": "016f1c6b-973c-45c8-8760-8b859f4679aa",
      "conversationGuid": "9ea4ee2c-d932-47cb-b5d2-9a5c9bb8f097",
      "start": "2019-12-19T14:14:05.283Z",
      "duration": 48569,
      "direction": "Inbound",
      "serviceName": "Report Gp 2",
      "connectTo": "0123456789",
      "connectFrom": "0987654321",
      "interactionPlanMapping": {
        "addressName": "Main Support Number",
        "mappingName": "Mapping1",
        "interactionPlanName": "Customer Support Plan"
      },
      "channels": [
        {
          "guid": "016f1c6b-973c-45c8-8760-8b859f4679aa",
          "offset": 0,
          "duration": 45862,
          "endReason": "Released",
          "party": {
            "id": null,
            "role": "External",
            "touchpoint": "0987654321"
          },
          "events": [
            {
              "type": "Ringing",
              "offset": 0,
              "name": null,
              "duration": 0,
              "properties": null
            },
            {
              "type": "Connected",
              "offset": 0,
              "name": null,
              "duration": 45862,
              "properties": null
            },
            {
              "type": "InteractionPlan",
              "offset": 66,
              "name": "Customer Support Plan",
              "duration": 45796,
              "properties": {
                "reportingGroup": "Report Gp 2"
              }
            },
            {
              "type": "Applet",
              "offset": 122,
              "name": "Welcome",
              "duration": 0,
              "properties": {
                "appletType": "Announcement"
              }
            },
            {
              "type": "Applet",
              "offset": 170,
              "name": "Call Record",
              "duration": 0,
              "properties": {
                "appletType": "CallRecording"
              }
            },
            {
              "type": "Applet",
              "offset": 2960,
              "name": "MainMenu1",
              "duration": 0,
              "properties": {
                "appletType": "Menu"
              }
            },
            {
              "type": "Applet",
              "offset": 7087,
              "name": "SkillTag1",
              "duration": 0,
              "properties": {
                "appletType": "SkillTagger"
              }
            },
            {
              "type": "Applet",
              "offset": 7603,
              "name": "ACD1",
              "duration": 0,
              "properties": {
                "appletType": "ACD"
              }
            },
            {
              "type": "Queue",
              "offset": 7775,
              "name": "ACD1",
              "duration": 8098,
              "properties": {
                "interactionPlan": "0123456789",
                "interactionPlanName": "Customer Support Plan",
                "presentedSkills": [
                  "Billing"
                ],
                "result": "Delivered"
              }
            },
            {
              "type": "CallRecording",
              "offset": 15880,
              "name": null,
              "duration": 29982,
              "properties": null
            }
          ]
        },
        {
          "guid": "6acaf3a2-570b-47e7-8025-34b7f2e5a094",
          "offset": 8757,
          "duration": 39812,
          "endReason": "Released",
          "party": {
            "id": "01",
            "role": "Agent",
            "touchpoint": "01122334455"
          },
          "events": [
            {
              "type": "Ringing",
              "offset": 8757,
              "name": null,
              "duration": 7116,
              "properties": null
            },
            {
              "type": "Connected",
              "offset": 15873,
              "name": null,
              "duration": 28232,
              "properties": null
            },
            {
              "type": "CallRecording",
              "offset": 15880,
              "name": null,
              "duration": 28225,
              "properties": null
            },
            {
              "type": "Wrap",
              "offset": 44105,
              "name": null,
              "duration": 4464,
              "properties": null
            },
            {
              "type": "Disposition",
              "offset": 61042,
              "name": null,
              "duration": 0,
              "properties": {
                "disposition": "CallBack"
             }
            },
            {
              "type": "CallRating",
              "offset": 18358,
              "name": null,
              "duration": 0,
              "properties": {
                "classification": "3"
              }
            }
          ]
        }
      ]
    },
	...
  ],
  "upTo": "2019-12-19T14:18:32.395Z",
  "latestUpdate": "2019-12-19T14:18:25.862Z"
}

The response returns the first page of items. The metadata shows that there are 8 pages of results that contain the 200 items.

User requests a page outside of the range of available pages (pageCount)

Example request

https://***.api.newvoicemedia.com/stats/interactions?start=2019-12-19&page=9

The request includes a page number of 9.

Example response

{
  "meta": {
    "page": 9,
    "count": 25,
    "pageCount": 8,
    "totalCount": 200
  },
  "items": [],
  "upTo": "2019-12-19T14:19:32.395Z",
  "latestUpdate": "2019-12-19T14:19:25.862Z"
}

The response contains metadata but no items.