Voice CDR

Introduction

The CDR Web API exposes a set of HTTP REST endpoints which allow you to retrieve the Call Detail Records for your voice traffic. It uses JSON as the language of information exchange.

1.1 Identification

The IDs defined below can be obtained by contacting our Support Team.

Product Token (GUID)

The API requires the user to be in the possession of a Product Token. This ID must be present in every request inside an header named X-CM-PRODUCTTOKEN.

Voice Account ID (GUID)

The Voice Account ID must be provided for every request, since it identifies the traffic belonging to your account.

1.2 Filtering

The API uses a set of predefined query string parameters used for filtering the results.

Name Type Required Description
from DateTime UTC Yes The timestamp indicating the start date. (Maximum timespan is 1 week.)
to DateTime UTC Yes The timestamp indicating the end date. (Maximum timespan is 1 week.)
skip Numeric Yes The number of items to skip. Used for pagination.
take Numeric Yes The number of items to take. Used for pagination.
  • Minimal value is 1.
  • Maximum value is 10000.

1.3 Throttling

The API uses rate limiting to prevent (accidental) abuse and to safeguard the resources the API accesses. The time limit is set to one request every 5 minutes for each unique request.

The API uses the Voice Account ID, From and the Skip value to uniquely identify each request.

A 429 Too Many Requests response is returned when a user tries to access the same data within 5 minutes. The header Retry-After is added to the response indicating the amount of time left in seconds.

1.4 Pagination

The API requires the user to take pagination into account when requesting data. This is handled using the Skip and Take parameters in the query string.

Each response will contain the following headers to indicated the requested Skip and Take, and the total amount of data:

  • X-CM-Pagination-Skip
  • X-CM-Pagination-Take
  • X-CM-Pagination-Total

Code Examples:

EXAMPLE
X-CM-Pagination-Skip: 0
X-CM-Pagination-Take: 1
X-CM-Pagination-Total: 1

1.5 Important Notes

  • The data returned by the API contains only successful calls.
  • All timestamps are in UTC format. Please take this into consideration when requesting data.
  • Additional fields in the response message may be added in future version. Please take this into consideration when building your application.

Using the API

2.1 Connectivity

The base URL to be used is: https://api.cmtelecom.com/cdrapi/

2.2 Retrieving conversations

Retrieves the conversations for a single voice account.

GET v1/{voiceAccountId}/conversations

2.2.2 Request parameters

Name Type Required Description
voiceAccountId GUID Yes The ID identifying your traffic.
from DateTime UTC Yes The timestamp indicating the start date.
to DateTime UTC Yes The timestamp indicating the end date.
skip Numeric Yes The number of items to skip. Used for pagination.
take Numeric Yes The number of items to take. Used for pagination.
  • Minimal value is 1.
  • Maximum value is 10000.

Code Examples:

EXAMPLE
$ curl "https://api.cmtelecom.com/cdrapi/v1/17f23fdf-21cd-48cd-bf1d-45012659004f/conversations?from=2018-04-01T00:00:00&to=2018-04-02&skip=0&take=1" -H "X-CM-PRODUCTTOKEN: 65309724-15a9-4f8c-9dc0-af23bd11c3af"

2.2.3 Response

A successful request will return a JSON array containing the conversation objects.

Name Type Description
voiceAccountId GUID The ID identifying your traffic.
voiceAccountName Alphanumeric The name of your Voice Account.
externalReference Alphanumeric Unique identifier of the call. (if applicable)
callId Alphanumeric The unique Call Id identifing the call.
startedOn DateTime UTC The timestamp the call started.
answeredOn DateTime UTC The timestamp the call was answered.
finishedOn DateTime UTC The timestamp the call was finished.
durationInSeconds Numeric The duration in seconds.
isAnonymous Boolean Whether the call was anonymous.
direction Alphanumeric The direction of the call.
callerId Alphanumeric The phone number identifying the caller.
calleeId Alphanumeric The phone number identifying the callee.
calleeDestination Alphanumeric The callee's destination.
CalleeDestinationId Alphanumeric The callee's destination ID.
surchargeAmount Decimal, precision of 6 The surcharge amount. (if applicable)
surchargeType Alphanumeric Can be either 'Penalty surcharge' or 'Non-EER to EER'. (if applicable)
surchargeUnitPrice Decimal, precision of 6 Surcharge unit price per minute. (if applicable)
cost Decimal, precision of 6 Call cost.
currency Alpha Currency of the call cost.
unitPrice Decimal, precision of 6 Call cost per minute.
apiAccount Alphanumeric API account user name. (if applicable)
sipAccount Alphanumeric SIP account user name. (if applicable)

Code Examples:

EXAMPLE
[
  {
    "voiceAccountId": "17f23fdf-21cd-48cd-bf1d-45012659004f",
    "voiceAccountName": "MaxCorp B.V.",
    "callId": "f452122c-ec1c-423a-b664-48aa51112a26",
    "startedOn": "2018-03-01T07:46:46",
    "answeredOn": "2018-03-01T07:46:46",
    "finishedOn": "2018-03-01T07:46:56",
    "durationInSeconds": 11,
    "isAnonymous": false,
    "direction": "outbound",
    "callerId": "31612345678",
    "calleeId": "31612345670",
    "calleeDestination": "NETHERLANDS MOBILE VODAFONE",
    "surchargeAmount": null,
    "surchargeType": null,
    "surchargeUnitPrice": null,
    "cost": 0.0123
  }
]