Tutorial: Building a Basic Reporting API Request

Before you use the Reporting API to retrieve statistics, let's take a look at how to build a basic API request.

General format of a Reporting API request is:

curl https://api.cxengage.net/v1/tenants/<tenantId>/realtime-statistics/<statistic-type>
-u '<username>:<password>'

Click to expand the following topics to view more information about section of the request:

ClosedCxEngage API Endpoint (https://api.cxengage.net)

In your API call, use the endpoint based on your tenant's region:

  • For the North American region, use https://api.cxengage.net
  • For the European region, use https://eu-west-1-prod-api.cxengage.net

The API documentation uses the North American endpoint in the sample requests. If you are in the European region, replace it with the European endpoint.

ClosedVersion and Tenant Access (/v1/tenants/<tenantId>)

Add the API version and your CxEngage tenant each of your API calls using this path: v1/tenants/<tenantId>. Ensure that you have the correct permissions to access your tenant. If you don't know your Tenant ID, see Finding Object IDs.

ClosedStatistic Type (/realtime-statistics/<statistic-type>)

After the tenant path, you need to specify which statistic you want to return. Add /realtime-statistics/<statistic-type> to the request after the tenant parameter. For example,

v1/tenants/7d23df20-2461-11e7-9bf4-b883f2d63b7b/realtime-statistics/interactions-in-conversation-count

The list of available statistics grows on continuous release basis, therefore, the list is not documented in this reference. To view the current list of available statistics, use an API call to return the list. See Get a List of Available Statistics.

ClosedAuthentication Header -u '<username>:<password>'

Include the basic authentication header, with the credentials required to access your tenant. You can also use an authentication token. For more information about both authentication types, see Authentication.

For this tutorial, we’ll build an API call to retrieve information about the total number of interactions that are currently in a conversation. Here's what you need to do:

  1. Find the API name for the statistic that you want to retrieve. To get this information, choose one of the following options:
    1. Use an API request to Get a List of Available Statistics.
    2. Use the Data Dictionary.

    For this tutorial, interactions-in-conversation-count is the API name for the statistic that counts the total number of interactions that are currently in a conversation.

  2. Build your API request, including your basic authorization credentials. Use of the following syntax: 
    curl GET https://api.cxengage.net/v1/tenants/7d23df20-2461-11e7-9bf4-b883f2d63b7b/realtime-statistics/interactions-in-conversation-count
    -u 'sbright@hercompany.com:Password#1234'

If your request is successful, the request returns a response. For detailed examples of requests and responses, see Examples.

If unsuccessful, the request returns an error message. See Errors and Responses.