Requests

Request parameters

Path parameters

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

For example, in the GET useradmin/users/{name} endpoint, you must replace {name} with the real value for the user you require.

Query string parameters

User Admin API endpoints do not support string parameters.

Header parameters

All User Admin 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 User Admin 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.v2+json

authorization

Required To make a request to the User Admin 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 User Admin API endpoints have only a GET method and therefore do not accept request body parameters.

Dates and times

Internationalization

Use ISO 8601 formats for DateTimes, for example, 2016-06-13T13: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 0).
  • limit. The required number of items per page (current default 25). Maximum of 5000.

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

  • page. The current requested page. The first page of results is page 0.
  • 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

Request

https://***.api.newvoicemedia.com/useradmin/users

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

Response

{
  "meta": {
    "page": 0,
    "count": 25,
    "pageCount": 8,
    "totalCount": 200
  },
  "items": [
     {...},
     {...},
     ...
  ]
}

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

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

Request

https://***.api.newvoicemedia.com/useradmin/users?page=9

The request includes a page number of 9.

Response

{
  "meta": {
    "page": 9,
    "count": 25,
    "pageCount": 8,
    "totalCount": 200
  },
  "items": []
}

The response contains metadata but no items.