1. Introduction

    1. Authentication
    2. Pagination
  2. SIP Account

    1. Create SIP Account
    2. Get SIP Account
    3. Get SIP Account
    4. Get SIP Account Credentials
    5. Get SIP Account Endpoints
    6. Get SIP Account Config
    7. Update SIP Account Display Name
    8. Update SIP Account Endpoints
    9. Update SIP Account Config
    10. Enable SIP Account
    11. Disable SIP Account
    12. Reset SIP Account Password
    13. Delete SIP Account
    14. Delete SIP Account From Prison
  3. Voice Account

    1. Create Voice Account
  4. Requests

    1. Get Required Fields
    2. Create Phone Number Request
    3. Get Phone Number Requests
    4. Get Phone Number Request
    5. Get Phone Number Request Requirements
    6. Get Phone Number Request Statuses
    7. Create Phone Number Porting Request
    8. Get Phone Number Porting Requests
    9. Get Phone Number Porting Request
    10. Get Phone Number Porting Request Statuses
    11. Update Phone Number Porting Request
    12. Perform Phone Number Porting Request
    13. Cancel Phone Number Porting Request
  5. Phone Numbers

    1. Get Phone Numbers
    2. Export Phone Numbers To Excel
    3. Phone Number Configurations
    4. Update Phone Number Configurations
    5. Update Customer Alias
  6. Distribution Groups

    1. Create Distribution Group
    2. Get Distribution Groups
    3. Get Distribution Group
    4. Update Distribution Group
    5. Delete Distribution Group
    6. Create Endpoint(s)
    7. Get Endpoints
    8. Get Endpoint
    9. Update Endpoint
    10. Delete Endpoint
  7. CDR
    1. Throttling
    2. Important Notes
    3. Get Conversations

Introduction

The CM.com voice management API enables you to manage your voice related products, such as your SIP accounts, phone numbers and distribution groups. All actions described in this API can also be performed in the Voice Management App.

If you are looking for the API for our predefined voice apps such as the notification app or the one time password app, please see the Voice API Apps docs.

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 Guid (GUID)

The voice account Guid must be provided in the URL for every request. You can find the voice account Guid under API Settings in the Voice Management App (https://cm.com/app/voice-management).

Account Guid (GUID)

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

Organization ID (number, resellers only)

This organization identifier should be added in the URL for every request that needs it. You can find the organization ID for your organization under Reseller API Settings in the Voice Management App (https://cm.com/app/voice-management).

An example:

URL | AccountGuid 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.

Create SIP Account

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

Parameters

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

Response

201 Created

Response body

Name Description Required Schema
guid Unique identifier of the SIP account. Yes string (uuid)
createdOn The date on which the SIP account has been created. No datetime
customerAccountGuid Unique identifier of the voice account. Yes string (uuid)
name Display name of the SIP account. No string
username The username of the SIP account. Yes string
isActive Whether the SIP account is active or not. No boolean
config Configuration details. Yes Config

Config

Name Description Schema
cpsLimit The maximum calls per second limit. number
ccLimit The maximum concurrent channels limit. number
alwaysAnonymous All calls via this SIP account will be anonymous. boolean
defaultOutboundCallerId The CLI used when making outbound calls. This does not override a valid CLI that is already provided in the SIP invite. string
restrictionType Type of restriction, can be either Blacklist or Whitelist. string
primaryTrunkId The primary trunk ID. string
secondaryTrunkId The secondary trunk ID. string
blockNonEerToEer All calls with a non-European CLI to a European country will be blocked for this SIP account. boolean
allowPremium Allow calls to premium pay-per-minute or pay-per-call numbers. boolean
{
  "guid": uuid,
  "createdOn": datetime,
  "customerAccountGuid": uuid,
  "name": string,
  "username": string,
  "isActive": boolean,
  "config":
  {
    "cpsLimit": number,
    "ccLimit": number,
    "alwaysAnonymous": boolean,
    "hasAnonymousOverride": boolean,
    "defaultOutboundCallerId": string,
    "restrictionType": string,
    "primaryTrunkId": string,
    "secondaryTrunkId": string,
    "blockNonEerToEer": boolean,
    "allowPremium": boolean
  }
}

Example response

{
    "guid": "00000000-0000-0000-0000-000000000000",
    "createdOn": "2020-01-01T00:00:00",
    "customerAccountGuid": "00000000-0000-0000-0000-000000000000",
    "name": "Test display",
    "username": "test_username",
    "isActive": true,
    "config": 
    {
        "cpsLimit": 1,
        "ccLimit": 1,
        "alwaysAnonymous": false,
        "hasAnonymousOverride": false,
        "defaultOutboundCallerId": "",
        "restrictionType": "Blacklist",
        "primaryTrunkId": "outbound01",
        "secondaryTrunkId": "outbound02",
        "blockNonEerToEer": false,
        "allowPremium": false
    }
}

Get SIP Accounts

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

Parameters

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

Response

200 OK

Response body

Name Description Schema
guid Unique identifier of the SIP account. string (uuid)
createdOn Created date of SIP account. datetime
customerAccountGuid Unique identifier of the voice account. string (uuid)
name Name of the SIP account. string
username Username of the SIP account. string
isActive Whether the account is active or not. boolean
inPrison Whether the account has a temporary ban after entering the wrong password too many times. boolean
[
    {
        "guid": uuid,
        "createdOn": datetime,
        "customerAccountGuid": uuid,
        "name": string,
        "username": string,
        "isActive": boolean,
        "inPrison": boolean
    }
]

Example response

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

Get SIP Account

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

Parameters

Type Name Description Schema
Path voiceAccountGuid
required
Your voice account identifier. string (uuid)
Path sipAccountGuid
required
Your SIP account identifier. string (uuid)

Response

200 OK

Response body

Name Description Schema
guid Unique identifier of the SIP account. string (uuid)
createdOn Created date of SIP account. datetime
customerAccountGuid Unique identifier of the voice account. string (uuid)
name Name of the SIP account. string
username Username of the SIP account. string
isActive Whether the account is active or not. boolean
inPrison Whether the account has a temporary ban after entering the wrong password too many times. boolean
{
    "guid": uuid,
    "createdOn": datetime,
    "customerAccountGuid": uuid,
    "name": string,
    "username": string,
    "isActive": boolean,
    "inPrison": boolean
}

Example response

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

Get SIP Account Credentials

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

Parameters

Type Name Description Schema
Path voiceAccountGuid
required
Your voice account identifier. string (uuid)
Path sipAccountGuid
required
Your SIP Account identifier. string (uuid)

Response

200 OK

Response body

Name Description Schema
username Username of SIP account. string
password Value of the SIP account password. string
{
    "username": string,
    "password": string
}

Example response

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

Get SIP Account Endpoints

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

Parameters

Type Name Description Schema
Path voiceAccountGuid
required
Your voice account identifier. string (uuid)
Path sipAccountGuid
required
Your SIP Account identifier. string (uuid)

Response

200 OK

Response body

Name Description Schema
guid Unique identifier of the SIP endpoint. string (uuid)
createdOn Created date of SIP endpoint. datetime
ipAddress The external IP address of the endpoint. string
port Port of the SIP endpoint IP address. number
subnetMask Subnet mask of IP address. number
isTrusted Whether authentication is required for the SIP endpoints to use the SIP account or not. It is not recommended to put this to true. Yes boolean
{
    "guid": uuid,
    "createdOn": datetime,
    "ipAddress": string,
    "port": number,
    "subnetMask": number,
    "isTrusted": boolean
}

Example response

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

Get SIP Account Config

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

Parameters

Name Description Schema
Path voiceAccountGuid
required
Your voice account identifier. string (uuid)
Path sipAccountGuid
required
Your SIP account identifier. string (uuid)

Response

200 OK

Response body

Name Description Schema
cpsLimit The maximum calls per second limit. number
ccLimit The maximum concurrent channels limit. number
alwaysAnonymous All calls via this SIP account will be anonymous boolean
defaultOutboundCallerId The CLI used when making outbound calls. This does not override a valid CLI that is already provided in the SIP invite. string
restrictionType Type of restriction, can be either Blacklist or Whitelist. string
primaryTrunkId The primary trunk ID. string
secondaryTrunkId The secondary trunk ID. string
blockNonEerToEer All calls with a non-European CLI to a European country will be blocked for this SIP account. boolean
allowPremium Allow calls to premium pay-per-minute or pay-per-call numbers. boolean
{
    "cpsLimit": number,
    "ccLimit": number,
    "alwaysAnonymous": boolean,
    "defaultOutboundCallerId": string,
    "restrictionType": string,
    "primaryTrunkId": string,
    "secondaryTrunkId": string,
    "blockNonEerToEer": boolean,
    "allowPremium": boolean
}

Example response

{
    "cpsLimit": 1,
    "ccLimit": 1,
    "alwaysAnonymous": false,
    "defaultOutboundCallerId": "",
    "restrictionType": "Blacklist",
    "primaryTrunkId": "outbound01",
    "secondaryTrunkId": "outbound02",
    "blockNonEerToEer": false,
    "allowPremium": false
}

Update SIP Account Display Name

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

Parameters

Type Name Description Schema
Path voiceAccountGuid
required
Your voice account identifier. string (uuid)
Path sipAccountGuid
required
Your SIP account identifier. string (uuid)

Request

Request body

Name Description Schema
name Display name of SIP trunk. string (uuid)
{
    "name": string
}

Example request

[
    {
        "name": "new displayname"
    }
]

Response

200 OK

Response body

Name Description Schema
guid Unique identifier of the SIP account. string (uuid)
createdOn Created date of SIP account. datetime
customerAccountGuid Unique identifier of the voice account. string (uuid)
name Name of the SIP account. string
username Username of the SIP account. string
isActive Whether the account is active or not. boolean
{
    "guid": uuid,
    "createdOn": datetime,
    "customerAccountGuid": uuid,
    "name": string,
    "username": string,
    "isActive": boolean
}

Example response

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

Update SIP Account Endpoints

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

Parameters

Type Name Description Schema
Path voiceAccountGuid
required
Your voice account identifier. string (uuid)
Path sipAccountGuid
required
Your SIP account identifier. string (uuid)

Request

Request body

Name Description Required Schema
ipAddress SIP endpoint IP address. Yes string
port Port of the SIP endpoint IP address. No number
subnetMask Subnet mask of IP address. No number
isTrusted Whether authentication is required for the SIP endpoints to use the SIP account or not. It is not recommended to put this to true. Yes boolean
[
  {
    "ipAddress": "1.2.3.4",
    "port": 5060,
    "subnetMask": 0,
    "isTrusted": true
  }
]

Response

200 OK

Response body

{
  "guid": uuid,
  "createdOn": datetime,
  "ipAddress": string,
  "port": number,
  "subnetMask": number,
  "isTrusted": boolean
}

Example response

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

Update SIP Account Config

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

Parameters

Type Name Description Schema
Path voiceAccountGuid
required
Your voice account identifier. string (uuid)
Path sipAccountGuid
required
Your SIP account identifier. string (uuid)

Request

Request body

{
    "cpsLimit": number,
    "ccLimit": number,
    "alwaysAnonymous": boolean,
    "hasAnonymousOverride": boolean,
    "defaultOutboundCallerId": string,
    "restrictionType": string,
    "primaryTrunkId": string,
    "secondaryTrunkId": string,
    "blockNonEerToEer": boolean,
    "allowPremium": boolean
}

Example request

{
    "cpsLimit": 1,
    "ccLimit": 1,
    "alwaysAnonymous": false,
    "hasAnonymousOverride": false,
    "defaultOutboundCallerId": "",
    "restrictionType": "Blacklist",
    "primaryTrunkId": "outbound01",
    "secondaryTrunkId": "outbound02",
    "blockNonEerToEer": false,
    "allowPremium": false
}

Response

200 OK

Response body

Response body

Name Description Schema
cpsLimit The maximum calls per second limit. number
ccLimit The maximum concurrent channels limit. number
alwaysAnonymous All calls via this SIP account will be anonymous boolean
defaultOutboundCallerId The CLI used when making outbound calls. This does not override a valid CLI that is already provided in the SIP invite. string
restrictionType Type of restriction, can be either Blacklist or Whitelist. string
primaryTrunkId The primary trunk ID. string
secondaryTrunkId The secondary trunk ID. string
blockNonEerToEer All calls with a non-European CLI to a European country will be blocked for this SIP account. boolean
allowPremium Allow calls to premium pay-per-minute or pay-per-call numbers boolean
{
    "cpsLimit": number,
    "ccLimit": number,
    "alwaysAnonymous": boolean,
    "defaultOutboundCallerId": string,
    "restrictionType": string,
    "primaryTrunkId": string,
    "secondaryTrunkId": string,
    "blockNonEerToEer": boolean,
    "allowPremium": boolean
}

Example response

{
    "cpsLimit": 1,
    "ccLimit": 1,
    "alwaysAnonymous": false,
    "defaultOutboundCallerId": "",
    "restrictionType": "Blacklist",
    "primaryTrunkId": "outbound01",
    "secondaryTrunkId": "outbound02",
    "blockNonEerToEer": false,
    "allowPremium": false
}

Enable SIP Account

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

Parameters

Type Name Description Schema
Path voiceAccountGuid
required
Your voice account identifier. string (uuid)
Path sipAccountGuid
required
Your SIP account identifier. string (uuid)

Response

204 No Content

Disable SIP Account

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

Parameters

Type Name Description Schema
Path voiceAccountGuid
required
Your voice account identifier. string (uuid)
Path sipAccountGuid
required
Your SIP account identifier. string (uuid)

Response

204 No Content

Reset SIP Account Password

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

Parameters

Type Name Description Schema
Path voiceAccountGuid
required
Your voice account identifier. string (uuid)
Path sipAccountGuid
required
Your SIP account identifier. string (uuid)

Response

200 OK

Response body

Name Description Schema
username Username of SIP account. string
password New password for the SIP account. string
{
    "username": string,
    "password": string
}

Example response

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

Delete SIP Account

DELETE https://api.cm.com/voice-sipaccountsapi/v1/{voiceAccountGuid}/sipAccounts/{sipAccountGuid}

Parameters

Type Name Description Schema
Path voiceAccountGuid
required
Your voice account identifier. string (uuid)
Path sipAccountGuid
required
Your SIP account identifier. string (uuid)

Response

204 No Content

Delete SIP Account From Prison

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

Parameters

Type Name Description Schema
Path voiceAccountGuid
required
Your voice account identifier. string (uuid)
Path sipAccountGuid
required
Your SIP account identifier. string (uuid)

Response

204 No Content

Voice Accounts

This section describes API calls regarding managing voice accounts.

Create Voice Accounts

If you're a reseller, you can create up to 10 voice accounts with the following API call

POST https://api.cm.com/voice-accountsapi/v1/organization/{organizationId}

Parameters

Type Name Description Schema
Path organizationId
required
The organization identifier. number

Request

Request body

Voice Accounts

Name Description Required Schema
name The name of the new voice account. Yes string
billingType The type of billing: Prepaid or Postpaid. Yes string
[
    {
        "name": string,
        "billingType": string
    },
    {
        "name": string,
        "billingType": string
    }
]

Response

201 Created

Response body

PrepaidInfo is only included if the voice account is prepaid.

[
    {
        "createdOn": datetime,
        "guid": uuid,
        "name": uuid,
        "externalId": string,
        "externalName": string,
        "prepaidInfo": {
            "amount": decimal,
            "currency": string
        },
        "isActive": boolean
    },
    {
        "createdOn": datetime,
        "guid": uuid,
        "name": string,
        "externalId": string,
        "externalName": string,
        "prepaidInfo": {
            "amount": decimal,
            "currency": string
        },
        "isActive": boolean
    }
]

Example response

[
    {
        "createdOn": "2021-01-01T00:00:00",
        "guid": "00000000-0000-0000-0000-000000000000",
        "name": "Voice account 1 (Prepaid)",
        "externalId": "",
        "externalName": "",
        "prepaidInfo": {
            "amount": 1.0000,
            "currency": "EUR"
        },
        "isActive": false
    },
    {
        "createdOn": "2021-01-01T00:00:00",
        "guid": "00000000-0000-0000-0000-000000000000",
        "name": "Voice account 2 (Postpaid)",
        "externalId": "",
        "externalName": "",
        "isActive": false
    }
]

Requests

This section describes the process of creating and working with different type of Voice requests, such as phone number or porting requests.

Get Required Fields

Because of different rules and regulations in different countries, we may need certain additional information along with your request depending on the country related to the request. These required fields can be fetched with this endpoint, together with an example value describing the format in which it should be supplied.

If the response contains only an empty array, it means the country that the request is bound to does not require any required fields to be added.

GET https://api.cm.com/voice-phonenumberrequestapi/v1/{countryCode}/requiredfields

Parameters

Type Name Description Schema
Path countryCode
required
The country in ISO 3166-1 alpha-2 format. string

Response

200 OK

Response body

[
  {
    "field": string,
    "exampleValue": string
  }
]

Example response

[
  {
    "field": "btw_number",
    "exampleValue": "BE0999999999"
  }
]

Create Phone Number Request

POST https://api.cm.com/voice-phonenumberrequestapi/v1/{accountGuid}/numberrequests

This endpoint allows you to request one or more phone numbers for use in our platform. The prices bound to purchasing new numbers can be found in the voice management App.

If the requested numbers are directly available, they will be immediately assigned to the specified voice account. If they are not directly available, your order may take some time to complete. We will keep you informed on the status of your order via the supplied email address and (if given) via the supplied callback URL.

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. string (uuid)

Request

Request 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 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 Get Required Fields for the specifications. No KeyValuePair <string,string>
callbackUrl URL that will be called when there is a status update, the body will contain the same response as this endpoint. No string
{
  countryCode: string,
  areaCode: string,
  numberType: string,
  quantity: int,
  emailAddress: string,
  consecutive: boolean,
  comment: string,
  callbackUrl: string,
  company: {
    street: string,
    streetNumber: string,
    registrationNumber: string,
    postalCode: string,
    name: string,
    city: string,
    requiredFields: {
        string: string,
    }
  }
}

Example request

{
  "countryCode": "NL",
  "areaCode": "76",
  "numberType": "FIXED",
  "quantity": 5,
  "emailAddress": "[email protected]",
  "consecutive": true,
  "comment": "Room for extra comments or requests regarding this phone number request",
  "callbackUrl": "https://www.my-callback-url.com/",
  "company": {
    "street": "Konijnenberg",
    "streetNumber": "24",
    "registrationNumber": "123456789",
    "postalCode": "4825 BD",
    "name": "CM.com",
    "city": "Breda",
    "requiredFields": {}
  }
}

Response (numbers not directly available)

200 OK, next to this an email will be sent out to the supplied emailAddress field with the order confirmation.

Response body

[
  {
    id: string,
    start: number,
    size: number,
    countryCode: string,
    typeId: number,
    status: string,
    voiceAccountGuid: string,
    validFrom: Date,
    validTo: Date,
    orderId: string
  }
];

Example response

[
  {
    "id": null,
    "start": null,
    "size": 5,
    "countryCode": "NL",
    "typeId": null,
    "status": "Requested",
    "voiceAccountGuid": "00000000-0000-0000-0000-000000000000",
    "validFrom": null,
    "validTo": null,
    "orderId": "220101001"
  }
]

Response (numbers directly available)

200 OK, next to this an email will be sent out to the supplied emailAddress field with the order confirmation.

Response body

[
  {
    id: string,
    start: number,
    size: number,
    countryCode: string,
    typeId: number,
    status: string,
    voiceAccountGuid: string,
    validFrom: Date,
    validTo: Date,
    orderId: string
  }
];

Example response

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "start": 31760000000,
    "size": 5,
    "countryCode": "NL",
    "typeId": 1,
    "status": "Operational",
    "voiceAccountGuid": "00000000-0000-0000-0000-000000000000",
    "validFrom": "2021-01-01T00:00:00Z",
    "validTo": null,
    "orderId": null
  }
]

Get Phone Number Requests

Get a list of all phone number requests.

GET https://api.cm.com/voice-phonenumberrequestapi/v1/{accountGuid}/numberrequests

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. string (uuid)
Query skip Amount of items skipped.
Default is 0.
number
Query take Amount of items retrieved.
Default is 30.
number
Query q Search for orderId of request. string
Query statuses Filter on status of request. Statuses key can be found here string

Response

200 OK

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

Response body

[
    {
        id: uuid,
        orderId: number,
        createdOn: Date,
        status: string,
        comment: string,
        requestData: {
            countryCode: string,
            areaCode: string,
            numberType: string,
            quantity: number,
            consecutive: boolean,
            requestedRanges: [
                {
                    size: number,
                    quantity: number
                }
            ],
            emailAddress: string,
            callbackUrl: string,
            comment: string,
            company: {
                name: string,
                registrationNumber: string,
                city: string,
                postalCode: string,
                street: string,
                streetNumber: string,
                requiredFields: {
                    requiredField1: string
                }
            }
        }
    }
]

Example response

[
    {
        "id": "00000000-0000-0000-0000-000000000000",
        "orderId": 210101001,
        "createdOn": "2021-01-01T10:00:00",
        "status": "Requested",
        "comment": "Your numbers have been requested.",
        "requestData": {
            "countryCode": "NL",
            "areaCode": "76",
            "numberType": "FIXED",
            "quantity": 5,
            "consecutive": true,
            "requestedRanges": [
                {
                    "size": 10,
                    "quantity": 2
                }
            ],
            "emailAddress": "[email protected]",
            "callbackUrl": "https://www.my-callback-url.com/",
            "comment": "Room for extra comments or requests regarding this phone number request",
            "company": {
                "street": "Konijnenberg",
                "streetNumber": "24",
                "registrationNumber": "123456789",
                "postalCode": "4825 BD",
                "name": "CM.com",
                "city": "Breda",
                "requiredFields": {}
            }
        }
    }
]

Get Phone Number Request

Get a specific phone number request based on the given order ID.

GET https://api.cm.com/voice-phonenumberrequestapi/v1/{accountGuid}/numberrequests/{orderId}

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. string (uuid)
Path orderId
required
Unique identifier of the number request order, this can be found in your confirmation email or the voice management App. string

Response

200 OK

Response body

{
    id: uuid,
    orderId: number,
    createdOn: Date,
    status: string,
    comment: string,
    requestData: {
        countryCode: string,
        areaCode: string,
        numberType: string,
        quantity: number,
        consecutive: boolean,
        requestedRanges: [
            {
                size: number,
                quantity: number
            }
        ],
        emailAddress: string,
        callbackUrl: string,
        comment: string,
        company: {
            name: string,
            registrationNumber: string,
            city: string,
            postalCode: string,
            street: string,
            streetNumber: string,
            requiredFields: {
                requiredField1: string
            }
        }
    }
}

Example response

{
    "id": "00000000-0000-0000-0000-000000000000",
    "orderId": 210101001,
    "createdOn": "2021-01-01T10:00:00",
    "status": "Requested",
    "comment": "Your numbers have been requested.",
    "requestData": {
        "countryCode": "NL",
        "areaCode": "76",
        "numberType": "FIXED",
        "quantity": 5,
        "consecutive": true,
        "requestedRanges": [
            {
                "size": 10,
                "quantity": 2
            }
        ],
        "emailAddress": "[email protected]",
        "callbackUrl": "https://www.my-callback-url.com/",
        "comment": "Room for extra comments or requests regarding this phone number request",
        "company": {
            "street": "Konijnenberg",
            "streetNumber": "24",
            "registrationNumber": "123456789",
            "postalCode": "4825 BD",
            "name": "CM.com",
            "city": "Breda",
            "requiredFields": {}
        }
    }
}

Get Phone Number Request Requirements

Because of different rules and regulation in different countries, we may need additional information (for example documents) after your request has been created. The required information will be checked by our support staff. Necessary documents can later be requested via email. With this endpoint you can retrieve the additional information based on the country related to the request.

If the response contains only an empty array, it means the country that the request is bound to does not require any information.

GET https://api.cm.com/voice-phonenumberrequestapi/v1/numberrequests/{countryCode}/requirements

Parameters

Type Name Description Schema
Path countryCode
required
The country in ISO 3166-1 alpha-2 format. string

Response

200 OK

Response body

[
    {
        "key": string
    }
]

Example response

[
    {
        "key": "proof_of_company_address"
    },
    {
        "key": "address_in_prefix_region"
    }
]

Get Phone Number Request Statuses

A phone number request goes through a set of predefined statuses during its lifespan. With this request you can retrieve all possible statuses.

GET https://api.cm.com/voice-phonenumberrequestapi/v1/numberrequests/statuses

Response

200 OK

Response body

[
    {
        "key": string,
        "displayValue": string
    }
]

Example Response

[
    {
        "key": "Requested",
        "displayValue": "Requested"
    },
    {
        "key": "InProgress",
        "displayValue": "In Progress"
    },
    {
        "key": "Rejected",
        "displayValue": "Rejected"
    },
    {
        "key": "Done",
        "displayValue": "Done"
    }
]

Create Phone Number Porting Request

POST https://api.cm.com/voice-phonenumberrequestapi/v1/{accountGuid}/portingrequests

This endpoint allows you to request one or more phone numbers to be ported from your current number provider, to CM.com.

After your porting request has been created, we will keep you informed on the status of your order via the supplied email address and (if given) via the supplied callback URL. If your porting request has been completed, the phone numbers will be directly available for use inside our platform.

Parameters

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

Request

Request body

Name Description Required Schema
ownerCompanyName The owner's company name. Yes string
ownerRegistrationNumber The owner's registration number. Yes string
ownerStreet The owner's street. Yes string
ownerStreetNumber The owner's house number. Yes string
ownerStreetNumberExt The owner's house number extension. No string
ownerPostalCode The owner's postal code. Yes string
ownerCity The owner's city. Yes string
providerCompanyName The provider's company name. Yes string
phoneNumbers The phone number(s) to be ported. Yes PortingPhoneNumber list
comment Comment for extra information. No string
emailAddresses One or more (5 max) email addresses for confirmation and updates. Yes string[]
preferredPortingDateTime Only used for porting non-dutch numbers. 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
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 Get Required Fields for the specifications. No KeyValuePair <string,string>
callbackUrl URL that will be called when there is a status update, the body will contain the same response as this endpoint. No string
phoneNumberConfig The configuration to be applied once the porting has been completed. For more information, please see Update phone number configurations. No PortingPhoneNumberConfig

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

PortingPhoneNumberConfig

Name Description Required Schema
distributionGroupGuid The Distribution Group. Yes uuid
algorithm The algorithm that should be applied, can be either RoundRobin or FailOver. 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
{
    ownerCompanyName: string,
    ownerRegistrationNumber: string,
    ownerStreet: string,
    ownerStreetNumber: string,
    ownerStreetNumberExt: string,
    ownerPostalCode: string,
    ownerCity: string,
    providerCompanyName: string,
    phoneNumbers:
    [
        {
            phoneNumber: number,
            lastPhoneNumber: number,
            countryOfOrigin: string,
            includeInPhoneRegister: boolean
        }
    ],
    comment: string,
    emailAddresses: string[],
    preferredPortingDateTime: string,
    callbackUrl: string,
    requiredFields: {
        string: string,
    },
    phoneNumberConfig: {
        distributionGroupGuid: uuid,
        algorithm: string,
        anonymousMode: number
    }
}

Example request

{
    "ownerCompanyName": "CM.com",
    "ownerRegistrationNumber": "123456789",
    "ownerStreet": "Konijnenberg",
    "ownerStreetNumber": "24",
    "ownerStreetNumberExt": "B2",
    "ownerPostalCode": "4825 BD",
    "ownerCity": "Breda",
    "providerCompanyName": "T-Mobile",
    "phoneNumbers": [
        {
            "phoneNumber": 311234567890,
            "lastPhoneNumber": null,
            "countryOfOrigin": "Netherlands",
            "includeInPhoneRegister": false
        }
    ],
    "comment": "Room for extra comments or requests regarding this porting request",
    "emailAddresses": ["[email protected]", "[email protected]"],
    "preferredPortingDateTime": "2030-01-01T07:00:00.000Z",
    "callbackUrl": "https://www.my-callback-url.com/",
    "requiredFields": {},
    "phoneNumberConfig": {
        "distributionGroupGuid": "00000000-0000-0000-0000-000000000000",
        "algorithm": "RoundRobin",
        "anonymousMode": 1
    }
}

Response

201 Created

Response body

{
    "id": uuid,
    "orderId": string,
    "createdOn": datetime,
    "firstPossibleDate": datetime,
    "status": {
        "id": number,
        "key": string,
        "displayValue": string
    },
    "statusReason": string,
    "portingData": {
        "ownerCompanyName": string,
        "ownerRegistrationNumber": string,
        "ownerStreet": string,
        "ownerStreetNumber": string,
        "ownerStreetNumberExt": string,
        "ownerPostalCode": string,
        "ownerCity": string,
        "providerCompanyName": string,
        "phoneNumbers": [
            {
                "phoneNumber": number,
                "lastPhoneNumber": number,
                "countryOfOrigin": string,
                "includeInPhoneRegister": boolean
            }
        ],
        "comment": string,
        "emailAddresses": [string, string],
        "preferredPortingDateTime": datetime,
        "callbackUrl": string,
        "requiredFields": {
            "field": string
        },
        "phoneNumberConfig": {
            "distributionGroupGuid": uuid,
            "algorithm": string,
            "anonymousMode": number
        }
    }
}

Example response

{
    "id": "00000000-0000-0000-0000-000000000000",
    "orderId": "210101001",
    "createdOn": "2021-01-01T10:00:00",
    "firstPossibleDate": "2021-06-01T00:00:00",
    "status": {
        "id": 1,
        "key": "Requested",
        "displayValue": "Requested"
    },
    "statusReason": "Your porting request has been received.",
    "portingData": {
        "ownerCompanyName": "CM.com",
        "ownerRegistrationNumber": "123456789",
        "ownerStreet": "Konijnenberg",
        "ownerStreetNumber": "24",
        "ownerStreetNumberExt": "B2",
        "ownerPostalCode": "4825 BD",
        "ownerCity": "Breda",
        "providerCompanyName": "T-Mobile",
        "phoneNumbers": [
            {
            "phoneNumber": 311234567890,
            "lastPhoneNumber": null,
            "countryOfOrigin": "Netherlands",
            "includeInPhoneRegister": false
            }
        ],
        "comment": "Room for extra comments or requests regarding this porting request",
        "emailAddresses": ["[email protected]", "[email protected]"],
        "preferredPortingDateTime": "2030-01-01T07:00:00.000Z",
        "callbackUrl": "https://www.my-callback-url.com/",
        "requiredFields": {},
        "phoneNumberConfig": {
            "distributionGroupGuid": "00000000-0000-0000-0000-000000000000",
            "algorithm": "RoundRobin",
            "anonymousMode": 1
        }
    }
}

Get Phone Number Porting Requests

Get a list of all phone number porting requests.

GET https://api.cm.com/voice-phonenumberrequestapi/v1/{accountGuid}/portingrequests

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. string (uuid)
Query skip Amount of items skipped.
Default is 0.
number
Query take Amount of items retrieved.
Default is 30.
number
Query q Search for orderId of porting. string
Query statuses Filter on status of porting. Statuses key can be found here string

Response

200 OK

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

Response body

[
    {
        id: uuid,
        orderId: string,
        createdOn: Date,
        firstPossibleDate: Date,
        status: {
            id: number,
            key: string,
            displayValue: string
        },
        statusReason: string,
        portingData: {
            ownerCompanyName: string,
            ownerRegistrationNumber: string,
            ownerStreet: string,
            ownerStreetNumber: string,
            ownerStreetNumberExt: string,
            ownerPostalCode: string,
            ownerCity: string,
            providerCompanyName: string,
            phoneNumbers:
            [
                {
                    phoneNumber: number,
                    lastPhoneNumber: number,
                    countryOfOrigin: string,
                    includeInPhoneRegister: boolean
                }
            ],
            comment: string,
            emailAddresses: string[],
            preferredPortingDateTime: string,
            callbackUrl: string,
            requiredFields: {
                string: string,
            },
            phoneNumberConfig: {
                distributionGroupGuid: uuid,
                algorithm: string,
                anonymousMode: number
            }
        }
    }
]

Example response

[
    {
        "id": "00000000-0000-0000-0000-000000000000",
        "orderId": "210101001",
        "createdOn": "2021-01-01T10:00:00",
        "firstPossibleDate": "2021-06-01T00:00:00",
        "status": {
            "id": 1,
            "key": "Requested",
            "displayValue": "Requested"
        },
        "statusReason": "Your porting request has been received.",
        "portingData": {
            "ownerCompanyName": "CM.com",
            "ownerRegistrationNumber": "123456789",
            "ownerStreet": "Konijnenberg",
            "ownerStreetNumber": "24",
            "ownerStreetNumberExt": "B2",
            "ownerPostalCode": "4825 BD",
            "ownerCity": "Breda",
            "providerCompanyName": "T-Mobile",
            "phoneNumbers": [
                {
                "phoneNumber": 311234567890,
                "lastPhoneNumber": null,
                "countryOfOrigin": "Netherlands",
                "includeInPhoneRegister": false
                }
            ],
            "comment": "Room for extra comments or requests regarding this porting request",
            "emailAddresses": ["[email protected]", "[email protected]"],
            "preferredPortingDateTime": "2030-01-01T07:00:00.000Z",
            "callbackUrl": "https://www.my-callback-url.com/",
            "requiredFields": {},
            "phoneNumberConfig": {
                "distributionGroupGuid": "00000000-0000-0000-0000-000000000000",
                "algorithm": "RoundRobin",
                "anonymousMode": 1
            }
        }
    }
]

Get Phone Number Porting Request

Get a specific phone number porting request based on the given order ID.

GET https://api.cm.com/voice-phonenumberrequestapi/v1/{accountGuid}/portingrequests/{orderId}

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. string (uuid)
Path orderId
required
Unique identifier of the number porting request order, this can be found in your confirmation email or the voice management App. string

Response

200 OK

Response body

{
    id: uuid,
    orderId: string,
    createdOn: Date,
    firstPossibleDate: Date,
    status: {
        id: number,
        key: string,
        displayValue: string
    },
    statusReason: string,
    portingData: {
        ownerCompanyName: string,
        ownerRegistrationNumber: string,
        ownerStreet: string,
        ownerStreetNumber: string,
        ownerStreetNumberExt: string,
        ownerPostalCode: string,
        ownerCity: string,
        providerCompanyName: string,
        phoneNumbers:
        [
            {
                phoneNumber: number,
                lastPhoneNumber: number,
                countryOfOrigin: string,
                includeInPhoneRegister: boolean
            }
        ],
        comment: string,
        emailAddresses: string[],
        preferredPortingDateTime: string,
        callbackUrl: string,
        requiredFields: {
            string: string,
        },
        phoneNumberConfig: {
            distributionGroupGuid: uuid,
            algorithm: string,
            anonymousMode: number
        }
    }
}

Example response

{
    "id": "00000000-0000-0000-0000-000000000000",
    "orderId": "210101001",
    "createdOn": "2021-01-01T10:00:00",
    "firstPossibleDate": "2021-06-01T00:00:00",
    "status": {
        "id": 1,
        "key": "Requested",
        "displayValue": "Requested"
    },
    "statusReason": "Your porting request has been received.",
    "portingData": {
        "ownerCompanyName": "CM.com",
        "ownerRegistrationNumber": "123456789",
        "ownerStreet": "Konijnenberg",
        "ownerStreetNumber": "24",
        "ownerStreetNumberExt": "B2",
        "ownerPostalCode": "4825 BD",
        "ownerCity": "Breda",
        "providerCompanyName": "T-Mobile",
        "phoneNumbers": [
            {
            "phoneNumber": 311234567890,
            "lastPhoneNumber": null,
            "countryOfOrigin": "Netherlands",
            "includeInPhoneRegister": false
            }
        ],
        "comment": "Room for extra comments or requests regarding this porting request",
        "emailAddresses": ["[email protected]", "[email protected]"],
        "preferredPortingDateTime": "2030-01-01T07:00:00.000Z",
        "callbackUrl": "https://www.my-callback-url.com/",
        "requiredFields": {},
        "phoneNumberConfig": {
            "distributionGroupGuid": "00000000-0000-0000-0000-000000000000",
            "algorithm": "RoundRobin",
            "anonymousMode": 1
        }
    }
}

Get Phone Number Porting Request Statuses

A phone number porting request goes through a set of predefined statuses during its lifespan. With this request you can retrieve all possible statuses to check the current status of your request based on the status ID.

GET https://api.cm.com/voice-phonenumberrequestapi/v1/portingrequests/statuses

Response

200 OK

Response body

[
    {
        "id": number,
        "key": string,
        "displayValue": string
    }
]

Example response

[
    {
        "id": 1,
        "key": "Requested",
        "displayValue": "Requested"
    },
    {
        "id": 2,
        "key": "InProgress",
        "displayValue": "In Progress"
    },
    {
        "id": 28,
        "key": "Delayed",
        "displayValue": "Delayed"
    },
    {
        "id": 22,
        "key": "ReadyToBePorted",
        "displayValue": "Ready to be ported"
    },
    {
        "id": 3,
        "key": "Blocked",
        "displayValue": "Blocked"
    },
    {
        "id": 25,
        "key": "Cancelled",
        "displayValue": "Cancelled "
    },
    {
        "id": 5,
        "key": "Completed",
        "displayValue": "Completed"
    }
]

Update Phone Number Porting Request

PUT https://api.cm.com/voice-phonenumberrequestapi/v1/{accountGuid}/portingrequests/{orderId}

This endpoint allows to update certain information regarding your porting request, such as the phone number configuration that will be applied once the porting request has been completed.

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. string (uuid)
Path orderId
required
Unique identifier of the number porting request order, this can be found in your confirmation email or the voice management app. string

Request

Request body

Name Description Required Schema
phoneNumberConfig The configuration to be applied once the porting has been completed. For more information, please see Update phone number configurations. No PortingPhoneNumberConfig

PortingPhoneNumberConfig

Name Description Required Schema
distributionGroupGuid The distribution group. Yes uuid
algorithm The algorithm that should be applied, can be either RoundRobin or FailOver. Yes string
anonymousMode The algorithm that should be applied, can be either 1 for Privacy Id Header or 2 for Anonymous Invalid Header. Yes number
{
    phoneNumberConfig: {
        distributionGroupGuid: uuid,
        algorithm: string,
        anonymousMode: number
    }
}

Example request

{
    "phoneNumberConfig": {
        "distributionGroupGuid": "00000000-0000-0000-0000-000000000000",
        "algorithm": "RoundRobin",
        "anonymousMode": 1
    }
}

Response

200 OK

Response body

{
    "id": uuid,
    "orderId": string,
    "createdOn": datetime,
    "firstPossibleDate": datetime,
    "status": {
        "id": number,
        "key": string,
        "displayValue": string
    },
    "statusReason": string,
    "portingData": {
        "ownerCompanyName": string,
        "ownerRegistrationNumber": string,
        "ownerStreet": string,
        "ownerStreetNumber": string,
        "ownerStreetNumberExt": string,
        "ownerPostalCode": string,
        "ownerCity": string,
        "providerCompanyName": string,
        "phoneNumbers": [
            {
                "phoneNumber": number,
                "lastPhoneNumber": number,
                "countryOfOrigin": string,
                "includeInPhoneRegister": boolean
            }
        ],
        "comment": string,
        "emailAddresses": [string, string],
        "preferredPortingDateTime": datetime,
        "callbackUrl": string,
        "requiredFields": {
            "field": string
        },
        "phoneNumberConfig": {
            "distributionGroupGuid": uuid,
            "algorithm": string,
            "anonymousMode": number
        }
    }
}

Example response

{
    "id": "00000000-0000-0000-0000-000000000000",
    "orderId": "210101001",
    "createdOn": "2021-01-01T10:00:00",
    "firstPossibleDate": "2021-06-01T00:00:00",
    "status": {
        "id": 1,
        "key": "Requested",
        "displayValue": "Requested"
    },
    "statusReason": "Your porting request has been received.",
    "portingData": {
        "ownerCompanyName": "CM.com",
        "ownerRegistrationNumber": "123456789",
        "ownerStreet": "Konijnenberg",
        "ownerStreetNumber": "24",
        "ownerStreetNumberExt": "B2",
        "ownerPostalCode": "4825 BD",
        "ownerCity": "Breda",
        "providerCompanyName": "T-Mobile",
        "phoneNumbers": [
            {
                "phoneNumber": 311234567890,
                "lastPhoneNumber": null,
                "countryOfOrigin": "Netherlands",
                "includeInPhoneRegister": false
            }
        ],
        "comment": "Room for extra comments or requests regarding this porting request",
        "emailAddresses": ["[email protected]", "[email protected]"],
        "preferredPortingDateTime": "2030-01-01T07:00:00.000Z",
        "callbackUrl": "https://www.my-callback-url.com/",
        "requiredFields": {},
        "phoneNumberConfig": {
            "distributionGroupGuid": "00000000-0000-0000-0000-000000000000",
            "algorithm": "RoundRobin",
            "anonymousMode": 1
        }
    }
}

Perform Phone Number Porting Request

POST https://api.cm.com/voice-phonenumberrequestapi/v1/{accountGuid}/portingrequests/{orderId}/perform

Only allowed for Dutch numbers.

This endpoint allows you to perform (and thus complete) your porting request, once its status is set to Ready to be ported. After calling this endpoint, the order will be finalized and the phone numbers coupled to the given porting request will be activated on our platform.

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. string (uuid)
Path orderId
required
Unique identifier of the number porting request order, this can be found in your confirmation email or the voice management App. string

Response

200 OK

Response body

{
    id: uuid,
    orderId: string,
    createdOn: Date,
    firstPossibleDate: Date,
    status: {
        id: number,
        key: string,
        displayValue: string
    },
    statusReason: string,
    portingData: {
        ownerCompanyName: string,
        ownerRegistrationNumber: string,
        ownerStreet: string,
        ownerStreetNumber: string,
        ownerStreetNumberExt: string,
        ownerPostalCode: string,
        ownerCity: string,
        providerCompanyName: string,
        phoneNumbers:
        [
            {
                phoneNumber: number,
                lastPhoneNumber: number,
                countryOfOrigin: string,
                includeInPhoneRegister: boolean
            }
        ],
        comment: string,
        emailAddresses: string[],
        preferredPortingDateTime: string,
        callbackUrl: string,
        requiredFields: {
            string: string,
        },
        phoneNumberConfig: {
            distributionGroupGuid: uuid,
            algorithm: string,
            anonymousMode: number
        }
    }
}

Example response

{
    "id": "00000000-0000-0000-0000-000000000000",
    "orderId": "210101001",
    "createdOn": "2021-01-01T10:00:00",
    "firstPossibleDate": "2021-06-01T00:00:00",
    "status": {
        "id": 5,
        "key": "Completed",
        "displayValue": "Completed"
    },
    "statusReason": "Your porting request has been completed",
    "portingData": {
        "ownerCompanyName": "CM.com",
        "ownerRegistrationNumber": "123456789",
        "ownerStreet": "Konijnenberg",
        "ownerStreetNumber": "24",
        "ownerStreetNumberExt": "B2",
        "ownerPostalCode": "4825 BD",
        "ownerCity": "Breda",
        "providerCompanyName": "T-Mobile",
        "phoneNumbers": [
            {
            "phoneNumber": 311234567890,
            "lastPhoneNumber": null,
            "countryOfOrigin": "Netherlands",
            "includeInPhoneRegister": false
            }
        ],
        "comment": "Room for extra comments or requests regarding this porting request",
        "emailAddresses": ["[email protected]", "[email protected]"],
        "preferredPortingDateTime": "2030-01-01T07:00:00.000Z",
        "callbackUrl": "https://www.my-callback-url.com/",
        "requiredFields": {},
        "phoneNumberConfig": {
            "distributionGroupGuid": "00000000-0000-0000-0000-000000000000",
            "algorithm": "RoundRobin",
            "anonymousMode": 1
        }
    }
}

Cancel Phone Number Porting Request

POST https://api.cm.com/voice-phonenumberrequestapi/v1/{accountGuid}/portingrequests/{orderId}/cancel

Only allowed for Dutch numbers.

This endpoint allows you to cancel an ongoing porting request, once its status is set to Ready to be ported. After calling this endpoint, the ongoing order process will be stopped.

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. string (uuid)
Path orderId
required
Unique identifier of the number porting request order, this can be found in your confirmation email or the voice management App. string

Response

200 OK

Response body

{
    id: uuid,
    orderId: string,
    createdOn: Date,
    firstPossibleDate: Date,
    status: {
        id: number,
        key: string,
        displayValue: string
    },
    statusReason: string,
    portingData: {
        ownerCompanyName: string,
        ownerRegistrationNumber: string,
        ownerStreet: string,
        ownerStreetNumber: string,
        ownerStreetNumberExt: string,
        ownerPostalCode: string,
        ownerCity: string,
        providerCompanyName: string,
        phoneNumbers:
        [
            {
                phoneNumber: number,
                lastPhoneNumber: number,
                countryOfOrigin: string,
                includeInPhoneRegister: boolean
            }
        ],
        comment: string,
        emailAddresses: string[],
        preferredPortingDateTime: string,
        callbackUrl: string,
        requiredFields: {
            string: string,
        },
        phoneNumberConfig: {
            distributionGroupGuid: uuid,
            algorithm: string,
            anonymousMode: number
        }
    }
}

Example response

{
    "id": "00000000-0000-0000-0000-000000000000",
    "orderId": "210101001",
    "createdOn": "2021-01-01T10:00:00",
    "firstPossibleDate": "2021-06-01T00:00:00",
    "status": {
        "id": 25,
        "key": "Cancelled",
        "displayValue": "Cancelled "
    },
    "statusReason": "Your porting request has been canceled",
    "portingData": {
        "ownerCompanyName": "CM.com",
        "ownerRegistrationNumber": "123456789",
        "ownerStreet": "Konijnenberg",
        "ownerStreetNumber": "24",
        "ownerStreetNumberExt": "B2",
        "ownerPostalCode": "4825 BD",
        "ownerCity": "Breda",
        "providerCompanyName": "T-Mobile",
        "phoneNumbers": [
            {
            "phoneNumber": 311234567890,
            "lastPhoneNumber": null,
            "countryOfOrigin": "Netherlands",
            "includeInPhoneRegister": false
            }
        ],
        "comment": "Room for extra comments or requests regarding this porting request",
        "emailAddresses": ["[email protected]", "[email protected]"],
        "preferredPortingDateTime": "2030-01-01T07:00:00.000Z",
        "callbackUrl": "https://www.my-callback-url.com/",
        "requiredFields": {},
        "phoneNumberConfig": {
            "distributionGroupGuid": "00000000-0000-0000-0000-000000000000",
            "algorithm": "RoundRobin",
            "anonymousMode": 1
        }
    }
}

Phone Numbers

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

Get Phone Numbers

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

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. 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

200 OK

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

Response body

Name Description Schema
number Phone number. number
originalNumber Original number. This is only applicable for some Belgian phone numbers. number
voiceAccount Voice account. Voice Account
validFrom The date when the number becomes valid. datetime
validTo The date when the number becomes invalid. datetime
numberType Type of number. string
updatedOn Date when the number has been updated. datetime
status The status of the phone number. Status

Voice Account

Name Description Schema
createdOn The date on which the voice account has been created. datetime
name Name of the voice account. string
productAccountId The unique identifier of a voice account. string (uuid)
externalId The external unique identifier of a voice account. number
externalName The external name of the voice account. string
isActive Whether the voice account is active or not. boolean
isTest Whether the voice account is a test or not. Will always be false. boolean

Application

Name Description Schema
guid Unique identifier of the application. string (uuid)
name Name of the application. string
isConfigurable Whether the application is configurable or not. boolean
displayCode The display code of the application. number

Distribution Group

Name Description Schema
guid Unique identifier of the application. string (uuid)
name Name of the application. string
createdOn The date on which the distribution group has been created. datetime
updatedOn The date on which the distribution group has been updated. datetime
dispatchers An array of dispatchers. dispatchers[]
inboundRoutes An array of inbound routes. Inbound Routes

Inbound Routes

Name Description Schema
createdOn The date of which the inbound route has been created. datetime
phoneNumber The phone number accepting inbound routes. long
description Description of the inbound route(s). string
distributionGroupId Distribution Group where the inbound traffic should be delivered. string (uuid)
distributionAlgorithm The algorithm that should be applied, can be either RoundRobin or FailOver. number

Country

Name Description Schema
code The country code. string
name The name of the country. string
prefix The prefix of the country. string
zone The zone where the country is located in. string

Status

Name Description Schema
guid The status unique identifier. string (uuid)
name The name of the status. Can be Requested or Operational. string

Response body

[
  {
    "number": string,
    "originalNumber": string,
    "voiceAccount": {
      "createdOn": datetime,
      "name": string,
      "productAccountId": uuid,
      "externalId": int,
      "externalName": string,
      "isActive": boolean,
      "isTest": boolean
    },
    "application": {
      "guid": uuid,
      "name": string,
      "isConfigurable": boolean,
      "displayCode": int
    },
    "distributionGroup": {
      "guid": uuid,
      "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": uuid,
      "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 Phone Numbers To Excel

GET https://api.cm.com/voice-phonenumberapi/v1/{accountGuid}/phonenumbers/export?exportAll=false

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. string (uuid)
Query exportAll
Export inbound numbers for all voice accounts within the organization.
Default value is false.
boolean

Response

File

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/{voiceAccountGuid}/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/{voiceAccountGuid}/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/{voiceAccountGuid}/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/{accountGuid}/phonenumbers

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. string (uuid)

Request

Request body

Name Description Required Schema
type The application type that the phone number should be configured to, can be cxbot,directforwarding,flowbuilder,notification,sip,voicepbx, or none. Yes string
phoneNumber Phone number. Yes number
distributionGroupGuid Unique identifier of distribution group. Yes string (uuid)
algorithm The algorithm that should be applied, can be either RoundRobin or FailOver. 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
appAccountGuid Unique identifier of app account. Yes number
promptType Type of prompt, can be either TTS or File. Yes string
language The selected voice language, format can be found here (If PromptType = TTS). Yes string
gender Gender of the voice (If PromptType = TTS). Yes string
voiceNumber The selected voice number (If PromptType = TTS). No number
timeoutInMilliseconds Determines when the attempt of calling the recipient should be cancelled. No number
callbackUrl Callback url for the voice API. Yes string
destinationNumber Destination number bound to this configuration. Yes number
customCallerId Custom number bound to this configuration. Yes number
[
  {
    "type": string,
    "phoneNumber": number
  },
  {
    "type": string,
    "phoneNumber": number,
    "distributionGroupGuid": uuid,
    "algorithm": string,
    "anonymousMode": number
  },
  {
    "type": string,
    "phoneNumber": number,
    "appAccountGuid": uuid,
    "promptType": string,
    "prompt": string,
    "language": string,
    "gender": string,
    "voiceNumber": number,
    "timeoutInMilliseconds": number,
    "callbackUrl": string
  },
  {
    "type": string,
    "phoneNumber": number,
    "appAccountGuid": uuid,
    "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 request

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

200 OK, 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": uuid,
    "algorithm": string,
    "anonymousMode": number
  },
  {
    "type": string,
    "phoneNumber": number,
    "appAccountGuid": uuid,
    "promptType": string,
    "prompt": string,
    "language": string,
    "gender": string,
    "voiceNumber": number,
    "timeoutInMilliseconds": number,
    "callbackUrl": string
  },
  {
    "type": string,
    "phoneNumber": number,
    "appAccountGuid": uuid,
    "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
  }
]

Update Phone Number Alias

You can use this endpoint to update the alias of a phone number.

PUT https://api.cm.com/voice-phonenumberapi/v1/phonenumberranges/{accountGuid}/phonenumbers/{phonenumber}/customeralias

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. string (uuid)
Path phonenumber
required
Your phone number. long

Request

Request body

Name Description Required Schema
customerAlias The new customer alias for the supplied number. Yes string
{
    "customerAlias": string
}

Example request

{
  "customerAlias": "Custom alias"
}

Response

200 OK

Response body

[
  {
    "originalNumber": number,
    "number": number,
    "customerAlias": string
  }
]

Example response

[
  {
    "originalNumber": null,
    "number": 311234567890,
    "customerAlias": "Custom alias"
  }
]

Distribution Groups

This section describes information regarding distribution groups that are linked to your account.

Create Distribution Group

Creates a new distribution group for the specified account.

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

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. string (uuid)

Request

Request body

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
{
    "name": string,
    "endpoints": 
    [
        {
            "name": string,
            "ipAddress": string,
            "port": int,
            "priority": int,
            "isActive": boolean
        }
    ]
}

Example request

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

Response

201 Created

Response body

Distribution Group

Name Description Required Schema
guid Unique identifier of the distribution group. Yes string
name The name of the distribution group. Yes string
createdOn When the distribution group was created. Yes string
updateOn When the distribution group was last updated. Yes string
endpoints The endpoints of the 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 UDP port of the endpoint.

Supported ports: 5060-5100.
Yes number
priority Order in which endpoints are tried when using algorithm "Failover". Does not have any effect when using algorithm "Round-robin". Yes number
isActive Determines whether the endpoint is active or not. Yes boolean
{
    "guid": uuid,
    "name": string,
    "createdOn": datetime,
    "updatedOn": datetime,
    "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",
    "createdOn": "2019-01-01T00:00:00",
    "updatedOn": "2019-01-01T00:00:00",
    "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
        }
    ]
}

Get Distribution Groups

Get distribution groups that are linked to the specified account.

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

Parameters

Type Name Description Schema
Path accountGuid
required
Your account identifier. This can be either a voice account ID, or your account ID. See Authentication for more information. string (uuid)

Response

200 OK

Response body

Name Description Required Schema
guid Unique identifier of the distribution group. Yes string
name The name of the distribution group. Yes string
createdOn When the distribution group was created. Yes string
updateOn TWhen the distribution group was updated. Yes string
endpoints The endpoints of the 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 Order in which endpoints are tried when using algorithm "Failover". Does not have any effect when using algorithm "Round-robin". Yes number
isActive Determines whether the endpoint should be active or not. Yes boolean
[
    {
        "guid": uuid,
        "name": string,
        "createdOn": datetime,
        "updatedOn": datetime,
        "endpoints": [
            {
                "guid": uuid,
                "name": string,
                "ipAddress": string,
                "port": int,
                "priority": int,
                "isActive": boolean
            }
        ]
    }
]

Example response

[
    {
        "guid": "00000000-0000-0000-0000-000000000001",
        "name": "Distribution Group 1",
        "createdOn": "2019-01-01T00:00:00",
        "updatedOn": "2019-01-01T00:00:00",
        "endpoints": [
            {
                "guid": "00000000-0000-0000-0000-000000000001",
                "name": "Endpoint 1",
                "ipAddress": "1.1.1.1",
                "port": 5060,
                "priority": 1,
                "isActive": true
            }
        ]
    },
    {
        "guid": "00000000-0000-0000-0000-000000000002",
        "name": "Distribution Group 2",
        "createdOn": "2019-01-01T00:00:00",
        "updatedOn": "2019-01-01T00:00:00",
        "endpoints": [
            {
                "guid": "00000000-0000-0000-0000-000000000001",
                "name": "Endpoint 2",
                "ipAddress": "2.2.2.2",
                "port": 5065,
                "priority": 1,
                "isActive": false
            }
        ]
    }
]

Get Distribution Group

Get a distribution group for the specified account and distribution group identifier.

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

Parameters

Type Name Description Schema
Path accountGuid
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

200 OK

Response body

Name Description Required Schema
guid Unique identifier of the distribution group. Yes string
name The name of the distribution group. Yes string
createdOn When the distribution group was created. Yes string
updateOn When the distribution group was last updated. Yes string
endpoints The endpoints of the 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 Order in which endpoints are tried when using algorithm "Failover". Does not have any effect when using algorithm "Round-robin". Yes number
isActive Determines whether the Endpoint should be active or not. Yes boolean
{
    "guid": uuid,
    "name": string,
    "createdOn": datetime,
    "updatedOn": datetime,
    "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",
    "createdOn": "2019-01-01T00:00:00",
    "updatedOn": "2019-01-01T00:00:00",
    "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/{accountGuid}/distributiongroups/{distributionGroupGuid}

Parameters

Type Name Description Schema
Path accountGuid
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)

Request

Request body

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 Order in which endpoints are tried when using algorithm "Failover". Does not have any effect when using algorithm "Round-robin". 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
        }
    ]
}

Example request

{
    "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-000000000001",
            "name": "Endpoint 2",
            "ipAddress": "1.1.1.2",
            "port": 5061,
            "priority": 2,
            "isActive": false
        }
    ]
}

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/{accountGuid}/distributiongroups/{distributionGroupGuid}

Parameters

Type Name Description Schema
Path accountGuid
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

Create Endpoint(s)

Create endpoint(s) for the specified account and distribution group identifier.

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

Parameters

Type Name Description Schema
Path accountGuid
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)

Request

Request body

Name Description Required Schema
name The name of the endpoint. Yes string
ipAddress The external IP address of the endpoint. Yes string
port The UDP port of the endpoint.

Supported ports: 5060-5100.
Yes number
priority Order in which endpoints are tried when using algorithm "Failover". Does not have any effect when using algorithm "Round-robin". Yes number
isActive Determines whether the endpoint should be active or not. Yes boolean
[
    {
        "name": string,
        "ipAddress": string,
        "port": int,
        "priority": int,
        "isActive": boolean
    }
]

Example request

[
    {
        "name": "Endpoint",
        "ipAddress": "1.1.1.1",
        "port": 5060,
        "priority": 1,
        "isActive": false
    }
]

Response

201 Created

Response body

Name Description Required Schema
guid Unique identifier of the endpoint. Yes string
name The name of the endpoint. Yes string
ipAddress The external IP Address of the endpoint. Yes string
port The UDP port of the endpoint.

Supported ports: 5060-5100.
Yes number
priority Order in which endpoints are tried when using algorithm "Failover". Does not have any effect when using algorithm "Round-robin". Yes number
isActive Determines whether the endpoint should be active or not. Yes boolean
[
    {
        "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": false
    }
]

Get Endpoints

Get endpoints of the distribution group for the specified account and distribution group identifier.

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

Parameters

Type Name Description Schema
Path accountGuid
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

200 OK

Response body

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

Get Endpoint

Get an endpoint for the specified account, distribution group identifier and endpoint identifier.

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

Parameters

Type Name Description Schema
Path accountGuid
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 identifier of the endpoint. string (uuid)

Response

200 OK

Response body

Name Description Required Schema
guid Unique identifier of the endpoint. Yes string
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 Order in which endpoints are tried when using algorithm "Failover". Does not have any effect when using algorithm "Round-robin". Yes number
isActive Determines whether the Endpoint should be active or not. Yes boolean
{
    "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
}

Update Endpoint

Updates a single endpoint for the specified account and identifiers.

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

Parameters

Type Name Description Schema
Path accountGuid
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 identifier of an endpoint. string (uuid)

Request

Request body

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 Order in which endpoints are tried when using algorithm "Failover". Does not have any effect when using algorithm "Round-robin". Yes number
isActive Determines whether the endpoint should be active or not. Yes boolean
{
    "name": string,
    "ipAddress": string,
    "port": int,
    "priority": int,
    "isActive": boolean
}

Example Request

{
    "name": "Endpoint 1",
    "ipAddress": "1.1.1.1",
    "port": 5060,
    "priority": 1,
    "isActive": true
}

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/{accountGuid}/distributiongroups/{distributionGroupGuid}/endpoints/{endpointGuid}

Parameters

Type Name Description Schema
Path accountGuid
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 identifier of the endpoint. string (uuid)

Response

204 No Content

CDR

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.

Get Conversations

Get the conversations for a single voice account.

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

Parameters

Type Name Description Schema
Path voiceAccountGuid
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

200 OK

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

Response body

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

Name Description Schema
voiceAccountId The ID identifying your traffic. string (uuid)
voiceAccountName The name of your voice account. string
externalReference Unique identifier of the call. (if applicable) string
callId The unique call ID identifying the call. string (uuid)
startedOn The timestamp the call started. datetime
answeredOn The timestamp the call was answered. datetime
finishedOn The timestamp the call was finished. datetime
durationInSeconds The duration in seconds. number
isAnonymous Whether the call was anonymous. boolean
direction The direction of the call. string
callerId The phone number identifying the caller. string
calleeId The phone number identifying the callee. string
calleeDestination The callee's destination. string
CalleeDestinationId The callee's destination ID. string
surchargeAmount The surcharge amount, precision of 4. (if applicable) decimal
surchargeType Can be either 'penalty surcharge' or 'Non-EER to EER'. (if applicable) string
surchargeUnitPrice Surcharge unit price per minute, precision of 4. (if applicable) decimal
cost Call cost, precision of 4. decimal
currency Currency of the call cost. string
unitPrice Call cost per minute, precision of 4. decimal
apiAccount API account user name. (if applicable) string
sipAccount SIP account user name. (if applicable) string
customSipAccountName Custom name of the SIP account. (if applicable) string
customResellerPrice Custom reseller price of the call, precision of 4. (only included for resellers) decimal
customResellerUnitPrice Custom reseller unit price per minute, precision of 4. (only included for resellers) decimal
customResellerSetupCost Custom reseller setup cost of the call, precision of 4 (if applicable). (only included for resellers) decimal
{
  "voiceAccountId": uuid,
  "voiceAccountName": string,
  "callId": uuid,
  "startedOn": datetime,
  "answeredOn": datetime,
  "finishedOn": datetime,
  "durationInSeconds": number,
  "isAnonymous": boolean,
  "direction": string,
  "callerId": string,
  "calleeId": string,
  "calleeDestination": string,
  "surchargeAmount": decimal,
  "surchargeType": string,
  "surchargeUnitPrice": decimal,
  "cost": decimal,
  "currency": string,
  "unitPrice": decimal
}

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,
    "currency": "EUR",
    "unitPrice": 0.03
  }
]