Introduction

This documentation provides information for the APIs related to Talk.

Authentication

API Key (GUID)

To make use of our APIs, you will need an API key in order to authenticate yourself.

This ID must be present in every request inside a header named X-CM-PRODUCTTOKEN. You can find the API Key for your voice account under API Settings in the Voice Management App (https://cm.com/app/voice-management).

Voice Account ID (GUID)

The Voice Account ID must be provided in the URL for every request.

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:

Header	Description	Schema
X-Cm-Pagination-Skip	Amount of items skipped.	number
X-Cm-Pagination-Take	Amount of items retrieved.	number
X-Cm-Pagination-Total	Total items that can be retrieved.	number

SIP Accounts

This section describes information regarding SIP Accounts that are linked to your Voice Account.

Retrieve SIP Accounts

GET https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your Voice Account identifier.	string (uuid)

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

[
    {
        "guid": "00000000-0000-0000-0000-000000000000",
        "createdOn": "2020-01-01T00:00:00",
        "customerAccountGuid": "voiceAccountId",
        "name": "Test display",
        "username": "test_username",
        "isActive": true,
        "inPrison": false
    }
]

Retrieve specific SIP Account

GET https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts/{sipAccountId}

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your Voice Account identifier.	string (uuid)
Path	sipAccountId required	Your SIP Account identifier.	string (uuid)

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

{
    "guid": "00000000-0000-0000-0000-000000000000",
    "createdOn": "2020-01-01T00:00:00",
    "customerAccountGuid": "voiceAccountId",
    "name": "Test display",
    "username": "test_username",
    "isActive": true,
    "inPrison": false
}

Retrieve SIP Account credentials

GET https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts/{sipAccountId}/credentials

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your Voice Account identifier.	string (uuid)
Path	sipAccountId required	Your SIP Account identifier.	string (uuid)

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

{
    "username": "test_username",
    "password": "test_password"
}

Retrieve SIP Accounts' endpoints

GET https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts/{sipAccountId}/sipEndpoints

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your Voice Account identifier.	string (uuid)
Path	sipAccountId required	Your SIP Account identifier.	string (uuid)

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

[
    {
        "guid": "00000000-0000-0000-0000-000000000000",
        "createdOn": "2020-01-01T00:00:00",
        "ipAddress": "1.2.3.4",
        "port": 0,
        "subnetMask": 32,
        "protocol": 2,
        "isTrusted": false
    }
]

Retrieve SIP Accounts' config

GET https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts/{sipAccountId}/config

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your Voice Account identifier.	string (uuid)
Path	sipAccountId required	Your SIP Account identifier.	string (uuid)

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

{
    "cpsLimit": 1,
    "ccLimit": 1,
    "alwaysAnonymous": false,
    "hasAnonymousOverride": false,
    "defaultOutboundCallerId": null,
    "restrictionType": "Blacklist",
    "setAsymmetricRtp": false,
    "primaryTrunkId": null,
    "secondaryTrunkId": null,
    "blockNonEerToEer": false,
    "allowPremium": false,
    "requiresDtmf": false,
    "requiresCcCli": false,
    "requiresSfb": false,
    "requiresEarlyMediaOn18X": false,
    "requiresAnonymousCalls": false,
    "requiresHighLoad": false,
    "requiresMobileCli": false,
    "requiresNonEerToEerTraffic": false
}

Create SIP Account

POST https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your Voice Account identifier.	string (uuid)

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

201 Created

{
    "guid": "00000000-0000-0000-0000-000000000000",
    "createdOn": "2020-01-01T00:00:00",
    "customerAccountGuid": "voiceAccountId",
    "name": "Test display",
    "username": "test_username",
    "isActive": true,
    "config": {
        "cpsLimit": 1,
        "ccLimit": 1,
        "alwaysAnonymous": false,
        "hasAnonymousOverride": false,
        "defaultOutboundCallerId": null,
        "restrictionType": "Blacklist",
        "setAsymmetricRtp": false,
        "primaryTrunkId": null,
        "secondaryTrunkId": null,
        "blockNonEerToEer": false,
        "allowPremium": false,
        "requiresDtmf": false,
        "requiresCcCli": false,
        "requiresSfb": false,
        "requiresEarlyMediaOn18X": false,
        "requiresAnonymousCalls": false,
        "requiresHighLoad": false,
        "requiresMobileCli": false,
        "requiresNonEerToEerTraffic": false
    }
}

Enable SIP Account

PUT https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts/{sipAccountId}/enable

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your Voice Account identifier.	string (uuid)
Path	sipAccountId required	Your SIP Account identifier.	string (uuid)

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

204 No Content

Disable SIP Account

PUT https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts/{sipAccountId}/disable

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your Voice Account identifier.	string (uuid)
Path	sipAccountId required	Your SIP Account identifier.	string (uuid)

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

204 No Content

Reset SIP Accounts' password

PUT https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts/{sipAccountId}/resetpassword

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your Voice Account identifier.	string (uuid)
Path	sipAccountId required	Your SIP Account identifier.	string (uuid)

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

{
    "username":"test_username",
    "password":"new_password"
}

Update SIP Accounts' display name

PUT https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts/{sipAccountId}/displayname

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your Voice Account identifier.	string (uuid)
Path	sipAccountId required	Your SIP Account identifier.	string (uuid)

Request Body

{
    "name": "new displayname"
}

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

{
    "guid": "00000000-0000-0000-0000-000000000000",
    "createdOn": "2020-01-01T00:00:00",
    "customerAccountGuid": "voiceAccountId",
    "name": "new displayname",
    "username": "test_username",
    "isActive": true
}

Update SIP Accounts' endpoints

PUT https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts/{sipAccountId}/sipEndpoints

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your Voice Account identifier.	string (uuid)
Path	sipAccountId required	Your SIP Account identifier.	string (uuid)

Request Body

[
  {
    "ipAddress": "1.2.3.4",
    "port": 5060,
    "subnetMask": 0,
    "protocol": 0,
    "isTrusted": true
  }
]

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

[
  {
    "ipAddress": "1.2.3.4",
    "port": 5060,
    "subnetMask": 0,
    "protocol": 0,
    "isTrusted": true
  }
]

Update SIP Accounts' config

PUT https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts/{sipAccountId}/config

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your Voice Account identifier.	string (uuid)
Path	sipAccountId required	Your SIP Account identifier.	string (uuid)

Request Body

{
    "cpsLimit": 1,
    "ccLimit": 1,
    "alwaysAnonymous": false,
    "hasAnonymousOverride": false,
    "defaultOutboundCallerId": null,
    "restrictionType": "Blacklist",
    "setAsymmetricRtp": false,
    "primaryTrunkId": null,
    "secondaryTrunkId": null,
    "blockNonEerToEer": false,
    "allowPremium": false,
    "requiresDtmf": false,
    "requiresCcCli": false,
    "requiresSfb": false,
    "requiresEarlyMediaOn18X": false,
    "requiresAnonymousCalls": false,
    "requiresHighLoad": false,
    "requiresMobileCli": false,
    "requiresNonEerToEerTraffic": false
}

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

{
    "cpsLimit": 1,
    "ccLimit": 1,
    "alwaysAnonymous": false,
    "hasAnonymousOverride": false,
    "defaultOutboundCallerId": null,
    "restrictionType": "Blacklist",
    "setAsymmetricRtp": false,
    "primaryTrunkId": null,
    "secondaryTrunkId": null,
    "blockNonEerToEer": false,
    "allowPremium": false,
    "requiresDtmf": false,
    "requiresCcCli": false,
    "requiresSfb": false,
    "requiresEarlyMediaOn18X": false,
    "requiresAnonymousCalls": false,
    "requiresHighLoad": false,
    "requiresMobileCli": false,
    "requiresNonEerToEerTraffic": false
}

Delete SIP Account

DELETE https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts/{sipAccountId}

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your voice account identifier.	string (uuid)
Path	sipAccountId required	Your sip account identifier.	string (uuid)

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

204 No Content

Delete SIP Account from prison

DELETE https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountId}/sipAccounts/{sipAccountId}/prison

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your voice account identifier.	string (uuid)
Path	sipAccountId required	Your sip account identifier.	string (uuid)

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

204 No Content

Inbound Numbers

This section describes information regarding inbound numbers that are linked to your voice account.

Retrieve inbound numbers in JSON

GET https://api.cm.com/inboundnumberapi/v2/{voiceAccountId}/inboundnumbers?skip=0&take=10

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your voice account identifier.	string (uuid)
Query	skip	Amount of items to skip. Minimum value is 0.	number
Query	take required	Amount of items to retrieve. Minimum value is 1.	number

Response

Response headers

Header	Description	Schema
X-Cm-Pagination-Skip	Amount of items skipped.	number
X-Cm-Pagination-Take	Amount of items retrieved.	number
X-Cm-Pagination-Total	Total items that can be retrieved.	number
Content-Type	application/json	-

Response body

[
  {
    "Number": string,
    "OriginalNumber": string,
    "VoiceAccount": {
      "CreatedOn": datetime,
      "Name": string,
      "ProductAccountId": string,
      "ExternalId": int,
      "ExternalName": string,
      "IsActive": boolean,
      "IsTest": boolean
    },
    "Application": {
      "Guid": string,
      "Name": string,
      "IsConfigurable": boolean,
      "DisplayCode": int
    },
    "DistributionGroup": {
      "guid": string,
      "name": string,
      "createdOn": datetime,
      "updatedOn": datetime,
      "dispatchers": [
      ],
      "inboundRoutes": [
        {
          "createdOn": datetime,
          "phoneNumber": long,
          "description": string,
          "distributionGroupId": int,
          "distributionAlgorithm": int
        }
      ]
    },
    "Country": {
      "Code": string,
      "Name": string,
      "Prefix": string,
      "Zone": string
    },
    "ValidFrom": datetime,
    "ValidTo": datetime?,
    "NumberType": string,
    "UpdatedOn": datetime,
    "Status": {
      "Guid": string,
      "Name": string
    }
  }
]

Example response

[
  {
    "Number": "31612345678",
    "OriginalNumber": "",
    "VoiceAccount": {
      "CreatedOn": "2019-01-01T00:00:00",
      "Name": "Voice account name",
      "ProductAccountId": "00000000-0000-0000-0000-000000000000",
      "ExternalId": 1,
      "ExternalName": "Voice account external name",
      "IsActive": true,
      "IsTest": false
    },
    "Application": {
      "Guid": "00000000-0000-0000-0000-000000000000",
      "Name": "SIP trunking",
      "IsConfigurable": true,
      "DisplayCode": 1
    },
    "DistributionGroup": null,
    "Country": {
      "Code": "NL",
      "Name": "Netherlands",
      "Prefix": "31",
      "Zone": "EER"
    },
    "ValidFrom": "2019-01-01T00:00:00",
    "ValidTo": null,
    "NumberType": "FIXED_LINE",
    "UpdatedOn": "2019-01-01T00:00:00",
    "Status": {
      "Guid": "00000000-0000-0000-0000-000000000000",
      "Name": "Operational"
    }
  }
]

Export inbound numbers to Excel

GET https://api.cm.com/inboundnumberapi/v2/{voiceAccountId}/inboundnumbers/export

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your voice account identifier.	string (uuid)

Response

Response headers

Header	Description	Schema
X-CM-FILENAME	Name of the generated Excel file.	string
Content-Type	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	-

Response body

The response body will contain the binary data of the Excel file.

CDR API

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.

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 uniqueness of a request is determined by the Voice Account ID, From and Skip values.

The API will respond with a 429 Too Many Requests when the same request is sent within 5 minutes. The header Retry-After is added to the response indicating the amount of time (in seconds) left.

Important Notes

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

Retrieve conversations

Retrieves the conversations for a single voice account.

GET https://api.cm.com/cdrapi/v1/{voiceAccountId}/conversations

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your voice account identifier.	string (uuid)
Query	skip	Amount of items to skip. Minimum value is 0.	number
Query	take required	Amount of items to retrieve. Minimum value is 1.	number

Response

Response headers

Header	Description	Schema
X-Cm-Pagination-Skip	Amount of items being skipped.	number
X-Cm-Pagination-Take	Amount of items being retrieved.	number
X-Cm-Pagination-Total	Total items that can be retrieved.	number
Content-Type	application/json	-

Response body

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 4	The surcharge amount. (if applicable)
surchargeType	Alphanumeric	Can be either 'Penalty surcharge' or 'Non-EER to EER'. (if applicable)
surchargeUnitPrice	Decimal, precision of 4	Surcharge unit price per minute. (if applicable)
cost	Decimal, precision of 4	Call cost.
currency	Alpha	Currency of the call cost.
unitPrice	Decimal, precision of 4	Call cost per minute.
apiAccount	Alphanumeric	API account user name. (if applicable)
sipAccount	Alphanumeric	SIP account user name. (if applicable)
customSipAccountName	Alphanumeric	Custom name of the SIP account. (if applicable)
customResellerPrice	Decimal, precision of 4	Custom reseller price of the call. (only included for resellers)

Example response

[
  {
    "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
  }
]