{

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.

Account ID (GUID)

This identifier can be found on the URL of CM.com's platform applications, after the language indicator.

An example:

URL | AccountID https://www.cm.com/en-gb/app/dashboard/00000000-0000-0000-0000-000000000000 | 00000000-0000-0000-0000-000000000000

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?exportAll=false

Parameters

Type Name Description Schema
Path voiceAccountId
required
Your voice account identifier. string (uuid)
Query exportAll
Export inbound numbers for all voice accounts within the organization.
Default value is false.
boolean

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.

Phone number configurations

There are a couple of different configurations for phone numbers. This section will explain them in detail.

No configuration

Name Description Required Schema
Type The type should be none Yes string
PhoneNumber The phone number to configure Yes number

SIP configuration

Name Description Required Schema
Type The type should be sip Yes string
PhoneNumber The phone number to configure Yes number
DistributionGroupGuid The distribution group used for the phone number, find the right Guid using the following endpoint: GET https://api.cm.com/voiceroutingapi/v1/{voiceAccountId}/distributiongroups Yes string (uuid)
Algorithm RoundRobin (shares all incoming calls over the given IPs) or Failover (looks at the first IP and only if that gives an error, the next one will be tried, etc.) Yes string
AnonymousMode If 1 is used and a call contains the Privacy:id header, the call will be passed 'as is'. If 2 is used and a call contains the Privacy:id header, all headers containing the callers' phone number will be stripped (P-Asserted-Identity, Remote-Party-ID) and the URI in the From header will be replaced with [email protected]. Yes number

Notification configuration

Name Description Required Schema
Type The type should be notification Yes string
PhoneNumber The phone number to configure Yes number
AppAccountGuid Find the Guid using the following endpoint: GET https://api.cm.com/voice-appaccountapi/v1/{voiceAccountId}/appaccounts Yes string (uuid)
PromptType File or TTS (Text To Speech) Yes string
Prompt The prompt message or the path of the audio file Yes string
Language Language formatted like 'en-GB' For TTS string
Gender Voice gender (Male or Female) For TTS string
VoiceNumber See the voice api docs for all the options https://www.cm.com/en-en/app/docs/voice-api-apps/v2.0 (Text-To-Speech) For TTS number
TimeoutInMilliseconds The time to let the phone ring at the receiver No number
CallbackUrl The URL (including http(s)://) for the callback. See https://www.cm.com/en-en/app/docs/voice-api-apps/v2.0 (Notification App callback) for more info. No string

Direct forwarding configuration

Name Description Required Schema
Type The type should be directforwarding Yes string
PhoneNumber The phone number to configure Yes number
AppAccountGuid Find the Guid using the following endpoint: GET https://api.cm.com/voice-appaccountapi/v1/{voiceAccountId}/appaccounts Yes string (uuid)
DestinationNumber The destination number to forward to Yes number
CustomCallerId Number alias No string

Update phone number configurations

PUT https://api.cm.com/voice-phonenumberapi/v1/{accountId}/phonenumbers

Body

The body contains all numbers you want to update with their desired configuration. It should be an array, see the following example with all the possible configurations:

[
  {
    "type": string,
    "phoneNumber": number
  },
  {
    "type": string,
    "phoneNumber": number,
    "distributionGroupGuid": string,
    "algorithm": string,
    "anonymousMode": number
  },
  {
    "type": string,
    "phoneNumber": number,
    "appAccountGuid": string,
    "promptType": string,
    "prompt": string,
    "language": string,
    "gender": string,
    "voiceNumber": number,
    "timeoutInMilliseconds": number,
    "callbackUrl": string
  },
  {
    "type": string,
    "phoneNumber": number,
    "appAccountGuid": string,
    "destinationNumber": number,
    "customCallerId": number
  }
  ...
]

It depends on the type of the configuration which items should be additionally added. See the following example body for all the possible configurations

Example body

[
  {
    "type": "none",
    "phoneNumber": 31612345678
  },
  {
    "type": "sip",
    "phoneNumber": 31612345678,
    "distributionGroupGuid": "00000000-0000-0000-0000-000000000000",
    "algorithm": "RoundRobin",
    "anonymousMode": 1
  },
  {
    "type": "notification",
    "phoneNumber": 31612345678,
    "appAccountGuid": "00000000-0000-0000-0000-000000000000",
    "promptType": "TTS",
    "prompt": "examplePrompt",
    "language": "en-GB",
    "gender": "Male",
    "voiceNumber": 1,
    "timeoutInMilliseconds": 0,
    "callbackUrl": null
  },
  {
    "type": "directforwarding",
    "phoneNumber": 31612345678,
    "appAccountGuid": "00000000-0000-0000-0000-000000000000",
    "destinationNumber": 31687654321,
    "customCallerId": null
  }
]

Response

The function will return the complete settings of the inserted body without the null values.

Response body

[
  {
    "type": string,
    "phoneNumber": number
  },
  {
    "type": string,
    "phoneNumber": number,
    "distributionGroupGuid": string,
    "algorithm": string,
    "anonymousMode": number
  },
  {
    "type": string,
    "phoneNumber": number,
    "appAccountGuid": string,
    "promptType": string,
    "prompt": string,
    "language": string,
    "gender": string,
    "voiceNumber": number,
    "timeoutInMilliseconds": number,
    "callbackUrl": string
  },
  {
    "type": string,
    "phoneNumber": number,
    "appAccountGuid": string,
    "destinationNumber": number,
    "customCallerId": number
  }
  ...
]

Example response

[
  {
    "type": "none",
    "phoneNumber": 31612345678
  },
  {
    "type": "sip",
    "phoneNumber": 31612345678,
    "distributionGroupGuid": "00000000-0000-0000-0000-000000000000",
    "algorithm": "RoundRobin",
    "anonymousMode": 1
  },
  {
    "type": "notification",
    "phoneNumber": 31612345678,
    "appAccountGuid": "00000000-0000-0000-0000-000000000000",
    "promptType": "TTS",
    "prompt": "examplePrompt",
    "language": "en-GB",
    "gender": "Male",
    "voiceNumber": 1,
    "timeoutInMilliseconds": 0
  },
  {
    "type": "directforwarding",
    "phoneNumber": 31612345678,
    "appAccountGuid": "00000000-0000-0000-0000-000000000000",
    "destinationNumber": 31687654321
  }
]

Request new number(s)

POST https://api.cm.com/voice-phonenumberapi/v1/{accountId}/phonenumbers/request

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information. string (uuid)

Body

Name Description Required Schema
countryCode The country in ISO 3166-1 alpha-2 format. Yes string
areaCode The area code (prefix) of the requested number. Yes string
numberType The type of the number: FIXED or TOLLFREE. Yes string
quantity The quantity of numbers to be requested. Yes int
emailAddress Contact info for CM Support. Yes string
consecutive Determines whether the numbers (if more than 1 are requested) should be in consecutive order. Default value is false. Yes boolean
comment Comment for extra information. No string
company Company information for new number requests. Yes Company

Company

Name Description Required Schema
street Street name. Yes string
streetNumber Street number. Yes string
registrationNumber The Company Registration Number (CRN) in order to identify your company. Yes string
postalCode Postal code. Yes string
Name Name of the company. Yes string
city City where the company is established. Yes string
requiredFields Depending on the countryCode of the numbers to be requested, we require additional fields that need to be supplied with the API call. See Required fields for the specifications. No KeyValuePair <string,string>
Required fields Country Name Description Schema
BE btw_number Business Registration Number of the company located in Belgium. string
FR siret_number Business Registration Number of the company located in France. string
{
  "countryCode": string,
  "areaCode": string,
  "numberType": string,
  "quantity": int,
  "emailAddress": string,
  "consecutive": boolean,
  "comment": string,
  "company": {
    "street": string,
    "streetNumber": string,
    "registrationNumber": string,
    "postalCode": string,
    "name": string,
    "city": string,
    "requiredFields": {
        "string": string,
    }
  }
}

Example body

{
  "countryCode": "NL",
  "areaCode": "3176",
  "numberType": "FIXED",
  "quantity": 5,
  "emailAddress": "[email protected]",
  "consecutive": true,
  "comment": "Extra comment",
  "company": {
    "street": "Test Street",
    "streetNumber": 123,
    "registrationNumber": 123456,
    "postalCode": "1234 AB",
    "name": "My company",
    "city": "Breda",
    "requiredFields": {}
  }
}

Response

200 OK

Request new number(s) porting

You can use this endpoint to submit a porting request for one or more numbers from your current provider to CM.

POST https://api.cm.com/voice-phonenumberapi/v1/{accountId}/phonenumbers/portingrequests

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information. string (uuid)

Body

Name Description Required Schema
ownerCompanyName The owner's company name. Yes string
ownerRegistrationNumber The owner's registration number. Yes string
ownerSiretNumber The owner's siret number. ONLY for French companies No string
ownerStreet The owner's street. Yes string
ownerStreetNumber The owner's street number. Yes string
ownerPostalCode The owner's postal code. Yes string
ownerCity The owner's city. Yes string
providerCompanyName The provider's company name. Yes string
providerStreet The provider's street. Yes string
providerStreetNumber The provider's street number. Yes string
providerPostalCode The provider's postal code. Yes string
providerCity The provider's city. Yes string
phoneNumbers The phone number(s) to be ported. Yes PortingPhoneNumber list
comment Comment for extra information. Yes string
emailAddress Email address for the request confirmation. Yes string
preferredPortingDateTime Preferred date and time to port the phone number(s) in UTC time. Will be picked up between 6:00 and 20:00 UTC time. No DateTime

Supported formats:
yyyy-MM-ddTHH:mm:ss
yyyy-MM-dd
MM-dd-yyyy

PortingPhoneNumber

Name Description Required Schema
phoneNumber The (first) phone number. Yes number
lastPhoneNumber If it's a range of phone numbers that should be ported, this is the last phone number in the range. No number
countryOfOrigin The country where the number originates from Yes string
includeInPhoneRegister Whether to include the phone number(s) in the phone register. Yes boolean
{
    "ownerCompanyName": string,
    "ownerRegistrationNumber": string,
    "ownerSiretNumber": string,
    "ownerStreet": string,
    "ownerStreetNumber": string,
    "ownerPostalCode": string,
    "ownerCity": string,
    "providerCompanyName": string,
    "providerStreet": string,
    "providerStreetNumber": string,
    "providerPostalCode": string,
    "providerCity": string,
    "phoneNumbers":
    [
        {
            "phoneNumber": number,
            "lastPhoneNumber": number,
            "countryOfOrigin": string,
            "includeInPhoneRegister": boolean
        }
    ],
    "comment": string,
    "emailAddress": string,
    "preferredPortingDateTime": string
}

Example body

{
    "ownerCompanyName": "Your company",
    "ownerRegistrationNumber": "123456789",
    "ownerSiretNumber": "",
    "ownerStreet": "Your Street",
    "ownerStreetNumber": "1",
    "ownerPostalCode": "1234 AA",
    "ownerCity": "Your City",
    "providerCompanyName": "Providing company",
    "providerStreet": "Their Street",
    "providerStreetNumber": "1",
    "providerPostalCode": "1234 BB",
    "providerCity": "Their City",
    "phoneNumbers":
    [
        {
            "phoneNumber": 311234567890,
            "lastPhoneNumber": null,
            "countryOfOrigin": "Netherlands",
            "includeInPhoneRegister": false
        }
    ],
    "comment": "Your Comment",
    "emailAddress": "[email protected]",
    "preferredPortingDateTime": "2030-01-01T07:00:00.000Z"
}

Response

204 No Content

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
Query from
required
The timestamp indicating the start date. DateTime

Supported formats:
yyyy-MM-ddTHH:mm:ss
yyyy-MM-dd
MM-dd-yyyy
Query to
required
The timestamp indicating the exclusive end date.
Maximum range is 1 week.
DateTime

Supported formats:
yyyy-MM-ddTHH:mm:ss
yyyy-MM-dd
MM-dd-yyyy

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
  }
]

Distribution Groups

This section describes information regarding Distribution Groups that are linked to your Account.

Retrieve Distribution Groups

Retrieves Distribution Groups that are linked to the specified Account.

GET https://api.cm.com/voice-distributiongroupsapi/v1/{accountId}/distributiongroups

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information. string (uuid)

Response

Response headers

Header Description Schema
Content-Type application/json -

Response body

[
    {
        "guid": uuid,
        "name": string,
        "endpoints": [
            {
                "guid": uuid,
                "name": string,
                "ipAddress": string,
                "port": int,
                "priority": int,
                "isActive": boolean
            }
        ]
    }
]

Example response

[
    {
        "guid": "00000000-0000-0000-0000-000000000000",
        "name": "Distribution Group 1",
        "endpoints": [
            {
                "guid": "00000000-0000-0000-0000-000000000000",
                "name": "Endpoint 1",
                "ipAddress": "1.1.1.1",
                "port": 5060,
                "priority": 1,
                "isActive": true
            }
        ]
    },
    {
        "guid": "00000000-0000-0000-0000-000000000000",
        "name": "Distribution Group 2",
        "endpoints": [
            {
                "guid": "00000000-0000-0000-0000-000000000000",
                "name": "Endpoint 2",
                "ipAddress": "2.2.2.2",
                "port": 5065,
                "priority": 1,
                "isActive": false
            }
        ]
    }
]

Retrieve Distribution Group

Retrieves a Distribution Group for the specified Account and Distribution Group identifier.

GET https://api.cm.com/voice-distributiongroupsapi/v1/{accountId}/distributiongroups/{distributionGroupGuid}

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information. string (uuid)
Path distributionGroupGuid
required
Unique identifier of the Distribution Group. string (uuid)

Response

Response headers

Header Description Schema
Content-Type application/json -

Response body

{
    "guid": uuid,
    "name": string,
    "endpoints": [
        {
            "guid": uuid,
            "name": string,
            "ipAddress": string,
            "port": int,
            "priority": int,
            "isActive": boolean
        },
        {
            "guid": uuid,
            "name": string,
            "ipAddress": string,
            "port": int,
            "priority": int,
            "isActive": boolean
        }
    ]
}

Example response

{
    "guid": "00000000-0000-0000-0000-000000000000",
    "name": "Distribution Group",
    "endpoints": [
        {
            "guid": "00000000-0000-0000-0000-000000000000",
            "name": "Endpoint 1",
            "ipAddress": "1.1.1.1",
            "port": 5060,
            "priority": 1,
            "isActive": true
        },
        {
            "guid": "00000000-0000-0000-0000-000000000000",
            "name": "Endpoint 2",
            "ipAddress": "1.1.1.2",
            "port": 5061,
            "priority": 2,
            "isActive": false
        }
    ]
}

Create Distribution Group

Creates a new Distribution Group for the specified Account.

POST https://api.cm.com/voice-distributiongroupsapi/v1/{accountId}/distributiongroups

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information. string (uuid)

Body

Distribution Group Name Description Required Schema
name The name of the Distribution Group. Yes string
endpoints The endpoints to be added when creating a new Distribution Group. No Endpoint list

Endpoint

Name Description Required Schema
name The name of the Endpoint. Yes string
ipAddress The external IP Address of the Endpoint. Yes string
port The port to be configured that is supported by CM.

Supported ports: 5060-5100.
Yes number
priority Determines the Round-Robin order of the Endpoint. Each endpoint inside a Distribution Group must have a unique priority. Yes number
isActive Determines whether the Endpoint should be active or not. Yes boolean
{
    "name": string,
    "endpoints": 
    [
        {
            "name": string,
            "ipAddress": string,
            "port": int,
            "priority": int,
            "isActive": boolean
        }
    ]
}

Response

201 Created

Response headers

Header Description Schema
Location https://api.cm.com/voice-distributiongroupsapi/v1/{accountId}/distributiongroups/{distributionGroupGuid} -
{
    "guid": uuid,
    "name": string,
    "endpoints": [
        {
            "guid": uuid,
            "name": string,
            "ipAddress": string,
            "port": int,
            "priority": int,
            "isActive": boolean
        },
        {
            "guid": uuid,
            "name": string,
            "ipAddress": string,
            "port": int,
            "priority": int,
            "isActive": boolean
        }
    ]
}

Example response

{
    "guid": "00000000-0000-0000-0000-000000000000",
    "name": "Distribution Group",
    "endpoints": [
        {
            "guid": "00000000-0000-0000-0000-000000000000",
            "name": "Endpoint 1",
            "ipAddress": "1.1.1.1",
            "port": 5060,
            "priority": 1,
            "isActive": true
        },
        {
            "guid": "00000000-0000-0000-0000-000000000000",
            "name": "Endpoint 2",
            "ipAddress": "1.1.1.2",
            "port": 5061,
            "priority": 2,
            "isActive": false
        }
    ]
}

Update Distribution Group

Updates a Distribution Group for the specified Account and Distribution Group identifier.

PUT https://api.cm.com/voice-distributiongroupsapi/v1/{accountId}/distributiongroups/{distributionGroupGuid}

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information. string (uuid)
Path distributionGroupGuid
required
Unique identifier of the Distribution Group. string (uuid)

Body

Distribution Group Name Description Required Schema
name The new name of the Distribution Group. Yes string
endpoints The endpoints to be added when updating the Distribution Group. No Endpoint list
{
    "name": string,
    "endpoints": 
    [
        {
            "name": string,
            "ipAddress": string,
            "port": int,
            "priority": int,
            "isActive": boolean
        }
    ]
}

Response

204 No Content

Delete Distribution Group

Deletes a Distribution Group for the specified Account and Distribution Group identifier.

DELETE https://api.cm.com/voice-distributiongroupsapi/v1/{accountId}/distributiongroups/{distributionGroupGuid}

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information. string (uuid)
Path distributionGroupGuid
required
Unique identifier of the Distribution Group. string (uuid)

Response

204 No Content

Retrieve Endpoints

Retrieves Endpoints of the Distribution Group for the specified Account and Distribution Group identifier.

GET https://api.cm.com/voice-distributiongroupsapi/v1/{accountId}/distributiongroups/{distributionGroupGuid}/endpoints

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information. string (uuid)
Path distributionGroupGuid
required
Unique identifier of the Distribution Group. string (uuid)

Response

Response headers

Header Description Schema
Content-Type application/json -

Response body

[
    {
        "guid": uuid,
        "name": string,
        "ipAddress": string,
        "port": int,
        "priority": int,
        "isActive": boolean
    },
    {
        "guid": uuid,
        "name": string,
        "ipAddress": string,
        "port": int,
        "priority": int,
        "isActive": boolean
    }
]

Example response

[
    {
        "guid": "00000000-0000-0000-0000-000000000000",
        "name": "Endpoint 1",
        "ipAddress": "1.1.1.1",
        "port": 5060,
        "priority": 1,
        "isActive": true
    },
    {
        "guid": "00000000-0000-0000-0000-000000000000",
        "name": "Endpoint 2",
        "ipAddress": "1.1.1.2",
        "port": 5062,
        "priority": 2,
        "isActive": true
    }
]

Retrieve Endpoint

Retrieves a Endpoint for the specified Account, Distribution Group identifier and Endpoint identifier.

GET https://api.cm.com/voice-distributiongroupsapi/v1/{accountId}/distributiongroups/{distributionGroupGuid}/endpoints/{endpointGuid}

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information. string (uuid)
Path distributionGroupGuid
required
Unique identifier of the Distribution Group. string (uuid)
Path endpointGuid
required
Unique identifer of the Endpoint. string (uuid)

Response

Response headers

Header Description Schema
Content-Type application/json -

Response body

{
    "guid": uuid,
    "name": string,
    "ipAddress": string,
    "port": int,
    "priority": int,
    "isActive": boolean
}

Example response

{
    "guid": "00000000-0000-0000-0000-000000000000",
    "name": "Endpoint",
    "ipAddress": "1.1.1.1",
    "port": 5060,
    "priority": 1,
    "isActive": true
}

Create Endpoint(s)

Create Endpoint(s) for the specified Account and Distribution Group identifier.

POST https://api.cm.com/voice-distributiongroupsapi/v1/{voiceAccountId}/distributiongroups/{distributionGroupGuid}/endpoints

Parameters

Type Name Description Schema
Path voiceAccountId
required
Your voice account identifier. string (uuid)
Path distributionGroupGuid
required
Unique identifier of the Distribution Group. string (uuid)

Body

See Endpoint for the definition.

[
    {
        "name": string,
        "ipAddress": string,
        "port": int,
        "priority": int,
        "isActive": boolean
    }
]

Response

204 No Content

Update Endpoint

Updates a single Endpoint for the specified Account and identifiers.

PUT https://api.cm.com/voice-distributiongroupsapi/v1/{accountId}/distributiongroups/{distributionGroupGuid}/endpoints/{endpointGuid}

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information. string (uuid)
Path distributionGroupGuid
required
Unique identifier of an Distribution Group. string (uuid)
Path endpointGuid
required
Unique identifer of an endpoint. string (uuid)

Body

See Endpoint for the definition.

{
    "name": string,
    "ipAddress": string,
    "port": int,
    "priority": int,
    "isActive": boolean
}

Response

204 No Content

Delete Endpoint

Deletes a Endpoint for the specified Account, Distribution Group identifier and Endpoint identifier.

DELETE https://api.cm.com/voice-distributiongroupsapi/v1/{accountId}/distributiongroups/{distributionGroupGuid}/endpoints/{endpointGuid}

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information. string (uuid)
Path distributionGroupGuid
required
Unique identifier of the Distribution Group. string (uuid)
Path endpointGuid
required
Unique identifer of the endpoint. string (uuid)

Response

204 No Content