Before you Begin

Some tips on using the Reports API code snippets. Also please review the Overview and refer to the API Reference. Call Details Records (CDRs) are often referred to in these topics as 'records'.

In this topic

• Query methods
• Common variables
• Request parameters
• Further request examples
• Request ID
• File ID
• See also

Query methods

The Reports API allows you to retrieve Call Details Records (CDRs), either synchronously or asynchronously. The synchronous approach is blocking and used where you want to obtain a small number of records (thousands). The records are returned in an array in the response.

If you want to run queries that will retrieve a vast number of records (millions), that may take longer, and is best done using an asynchronous approach. Usually an asynchronous request will take a callback URL parameter and POST a notification to the callback URL when the operation completes. The other option is to periodically query report status. The result using the asynchronous approach will be the generation of a Zip file containing a CSV file of records.

Common variables

When you use the code snippets you copy in your replacements for variables such as your API key and API secret, as well as other variables that control the API request. Some commonly replaced variables are shown in the following table:

Date ranges

For many of the calls you can specify either a message or call ID or a date range, but not both. The date ranges are from oldest to newest and are in ISO-8601 format.

The dates can use either of the following formats: yyyy-mm-ddThh:mm:ss[.sss]±hhmm or yyyy-mm-ddThh:mm:ss[.sss]Z.

This example shows fetching a list of records using a date range:

curl -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \
     "https://api.nexmo.com/v2/reports/records?account_id=abcd1234&product=MESSAGES&direction=outbound&date_start=2020-06-04T00:01:00Z&date_end=2020-06-04T00:02:00Z"

For dates containing a + in a GET query, where dates are passed as query parameters, you need to URL encode the dates, for example:

curl -G --data-urlencode date_start="2020-06-04T08:00:00+0000" --data-urlencode date_end="2020-06-04T14:00:00+0000" -u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \
     "https://api.nexmo.com/v2/reports/records?account_id=abcd1234&product=SMS&direction=outbound"

Product

The API calls Load Records Synchronously and Generate Report Asynchronously require you to specify a product. The product parameter specifies the Vonage API product for which reports and records are obtained. product can be one of SMS, VOICE-CALL, WEBSOCKET-CALL, VERIFY-API, NUMBER-INSIGHT, MESSAGES, CONVERSATIONS, or ASR.

The following table shows which API call use product:

Table legend: = required | = n/a

Request parameters for Load Records Synchronously

The parameters specified in API calls may vary depending on the product specified. The following table shows use of a parameter for different products:

Table legend: = required | 🔸 = optional | = n/a

Request parameters for Create Asynchronous Report

The parameters specified in API calls may vary depending on the product specified. The following table shows use of a parameter for different products:

Table legend: = required | 🔸 = optional | = n/a

Further request examples

You can find many examples of Reports API calls in the Curl code snippet repository. These examples show some additional calls in addition to the ones shown in the code snippet section here, and also demonstrate the use of product-specific parameters.

Request ID

When you request asynchronous creation of a report, a request ID will be returned. You can use this in subsequent calls, for example to check on report status, or cancel a report. An example response to an asynchronous report creation request is as follows:

{
  "request_id": "ri3p58f-48598ea7-1234-5678-9012-faabd79bdc2e",
  "request_status": "PENDING",
  "direction": "outbound",
  "product": "SMS",
  "account_id": "abcd1234",
  "date_start": "2020-05-21T13:27:00+0000",
  "date_end": "2020-05-21T13:57:00+0000",
  "include_subaccounts": false,
  "status": "delivered",
  "include_message": false,
  "receive_time": "2020-06-03T15:24:31+0000",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/ri3p58f-48598ea7-cb2d-1234-5678-fa1234567890"
    }
  }
}

File ID

The file_id is required to retrieve an asynchronously created report file. You can obtain the file_id from the details of a get report status or list reports call, or from the completion callback body. The response will contain JSON similar to:

    ...
    "download_report": {
    "href": "https://api.nexmo.com/v3/media/84a14d67-1234-5678-9012-ac042b16092a"
    }

In this case 84a14d67-1234-5678-9012-ac042b16092a is the FILE_ID.

See also

• API Reference