Trying out Vonage Contact Center APIs

When you have familiarized yourself with the Vonage Contact Center (VCC) APIs, you might want to run some requests.

How do I try out Vonage Contact Center APIs?

To enable you to quickly try out the APIs, we have provided them in a Postman collection.

What is a Postman collection?

Postman collections are groups of API endpoints that you can send requests to. Vonage Contact Center API endpoints are stored within a collection that you can run to get, create, update, and delete data. For more information about Postman collections, see Postman help.

How do I get the Postman collection?

Click Run in Postman (region) for your account's region on the home page of Vonage Contact Center APIs documentation or at the bottom of any endpoint page (other than Payment API and V0 API endpoints). A new browser tab opens. From here you can either view a read-only version of the collection in the public workspace (click View collection), or fork the collection to send requests to the API (click Fork Collection). Forking a collection makes a local copy of the API in your own workspace.

Forking collections in Postman

Click Fork Collection. If you're not signed in to postman, you will be prompted to do so. If you do not have an account, create one first.

When the Fork collection page opens, provide the following information:

• In Fork label, give your fork a name so you can identify it later.
• In Workspace, select the public, team, or personal workspace you want to fork the collection to.

Click Fork Collection. The forked API collection appears within your chosen workspace. We recommend that you watch for changes in the source collection, so that you can see when you need to pull changes into the forked collection. To watch the source collection, click Watch on the home tab of the source collection.

For more information about forking collections, including watching collections, see Postman help.

How do I prepare my Postman environment?

When you have forked the collection, the Vonage Contact Center APIs collection appears in your workspace in postman. To run requests, you must select and add some values to the active Postman environment that was included in the collection when you forked it. For information about Postman collections, see Postman help.

1. Select the active environment—EMEA, NAM, or APAC. By default, No Environment is selected in the upper-right area of Postman. The active environment you choose includes the region in which the APIs are run, and, later, the API credentials used to authenticate requests.
2. Edit environment variables. Click the eye icon alongside the chosen environment. In the dialog box that appears, click Edit in the top section. Provide values in the CURRENT VALUE column for the clientId and secret variables. Get these values from the VCC admin portal. For information about getting your clientId and secret, see Getting API credentials from VCC section in How to authenticate with a Vonage Contact Center (VCC) API. Save these values, either using Crtl+S, Cmd-S or by closing the tab and clicking Save (only in the desktop app).

For more information about working with Postman environments, see Postman help.

How do I get and set a bearer access token?

To send requests using VCC APIs, you will need a bearer access token to authenticate the requests.

To get a bearer access token, go to the POST /auth/connect/token endpoint in the applicable API and click Send. Your request runs in the region specified in your chosen environment, using the clientId and secret variables you saved in the environment and the appropriate scope for the API.

A successful response contains the bearer access token for this API and sets the value of 'token' for the collection to be used in subsequent requests. This token can only be used with this API; to make requests in a different API, you will need to get a bearer access token for that API. You will also need to rerun this request every two hours to continue using the API, as the token expires after this time.

How do I send API requests?

In the same way as you sent a request to get your bearer access token, for most endpoints, you can simply open the endpoint you want to send a request to and click Send.

Some endpoints, however, require additional parameters.

Path parameters

Some endpoints require a value that is part of the endpoint itself—this is a path parameter. For example, the GET /users/{userId} endpoint in the User Admin API requires a value for the userId parameter in the request. The endpoint uses the value to return data relating to the corresponding user only. In the path, replace <insert user ID here> with a specific userId. 

https://{{region}}.api.newvoicemedia.com/useradmin/users/8e22b1fe-d2ea-403d-8c03-50eb21188e79

Query parameters

Several of the endpoints can return large amounts of data, and such endpoints enable you to limit the data returned. For example, the GET /users endpoint in the User Admin API allows you to include Active, Archived, or All users in the response. You can also limit the number of items on each page of returned data and specify the page you'd like to return.

Specify these values in the Query Params list on the Params tab. When you have set a value, make sure you click to select the checkbox alongside the parameter's name to include it in the request.

https://{{region}}.api.newvoicemedia.com/useradmin/users?limit=500&include=All

Request body

Other endpoints (POST, PATCH, and PUT methods) require data that you must send within a JSON object in the request body.

For example, the POST /users endpoint requires a JSON object representing the new user in the request body. On the Body tab, a template for this object is provided. Replace values such as <insert users first and last name> and <insert country code such as GB> with specific values for a real user. You must provide all required values in the correct format or the response will contain a error messages. 

{
  "username": "<insert unique username>",
  "name": "<insert users first and last name>",
  "email": "<insert users email>",
  "ssoExternalId": "<insert users external sso Id>",
  "active": true,
  "userAccountConfiguration": {
    "role": "Supervisor",
    "actAsAgent": true,
    "agentConfiguration": {
      "agentDisplayId": "<insert unique agent display Id>",
      "webrtc": false,
      "enforcedDispositionCodes": false,
      "transcribeCalls": false,
      "screenRecording": false,
      "callParking": false,
      "salesCadence": false,
      "outboundAutoanswer": false,
      "inboundAutoanswer": false,
      "outboundWrapUp": 30,
      "backToReadyAfterNoAnswer": 30,
      "backToReadyAfterLineBusy": 30,
      "backToReadyAfterInvalidNumber": 30,
      "backToReadyAfterNetworkIssue": 30,
      "callRatingFrequency": 100,
      "location": "<insert country code such as GB>",
      "telephonyAddress": {
        "telephoneAddress": "<insert telephone number>",
        "outboundTelephonyRegion": "<insert telephony region ID>",
        "nationalDisplay": true,
        "virtualLocation": "<insert country code such as GB>"
      },
      "capacity": {
        "isAgentLevel": false,
        "live": 100,
        "nonLive": 50,
        "semiLive": 50
      },
      "associatedUsers": [
        {
          "username": "<insert VBC Username>",
          "applicationType": "VBC"
        }
      ]
    }
  }
}

How do I find documentation for an API or a specific endpoint?

Within Postman, we have included links to documentation for the APIs. For information about accessing documentation in Postman, see Postman help.

At the top level of the collection, you can access the documentation for all the Vonage Contact Center APIs. You can access documentation for specific APIs at the individual-API level.