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

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

Account ID (GUID)

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

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 | AccountID https://www.cm.com/en-gb/app/dashboard/00000000-0000-0000-0000-000000000000 | 00000000-0000-0000-0000-000000000000

Pagination

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

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

Header	Description	Schema
x-cm-pagination-skip	Amount of items skipped.	number
x-cm-pagination-take	Amount of items retrieved.	number
x-cm-pagination-total	Total items that can be retrieved.	number

SIP Accounts

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

Create SIP Account

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

201 Created

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

Get SIP Accounts

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

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

Get SIP Account

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

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

Get SIP Account credentials

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

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

Get SIP Account endpoints

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

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

Get SIP Account config

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

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

Update SIP Accounts' display name

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

Parameters

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

Request Body

{
    "name": "new displayname"
}

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

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

Update SIP Accounts' endpoints

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

Parameters

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

Request Body

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

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

Update SIP Accounts' config

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

Parameters

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

Request Body

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

200 OK

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

Enable SIP Account

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

204 No Content

Disable SIP Account

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

204 No Content

Reset SIP Accounts' password

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

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

Delete SIP Account

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

204 No Content

Delete SIP Account from prison

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

204 No Content

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

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 headers

Header	Description	Schema
Location	https://api.cm.com/voice-accountsapi/v1/{voiceAccountId}/voiceaccounts	-

PrepaidInfo is only included if the voice account is prepaid.

[
    {
        "createdOn": datetime,
        "guid": string,
        "name": string,
        "externalId": string,
        "externalName": string,
        "prepaidInfo": {
            "amount": decimal,
            "currency": string
        },
        "isActive": boolean
    },
    {
        "createdOn": datetime,
        "guid": string,
        "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.

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": "btw_number",
    "exampleValue": "BE0999999999"
  }
]

Create phone number request

POST https://api.cm.com/voice-phonenumberrequestapi/v1/{accountId}/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	accountId required	Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information.	string (uuid)

Body

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

Company

Name	Description	Required	Schema
street	Street name.	Yes	string
streetNumber	Street number.	Yes	string
registrationNumber	The Company Registration Number (CRN) in order to identify your company.	Yes	string
postalCode	Postal code.	Yes	string
Name	Name of the company.	Yes	string
city	City where the company is established.	Yes	string
requiredFields	Depending on the countryCode of the numbers to be requested, we require additional fields that need to be supplied with the API call. See Required fields for the specifications.	No	KeyValuePair <string,string>
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 body

{
  "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": 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/{accountId}/numberrequests

Parameters

Type	Name	Description	Schema
Path	accountId required	Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information.	string (uuid)
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

Response headers

Header	Description	Schema
Content-Type	application/json	-
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/{accountId}/numberrequests/{orderId}

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

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": "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": "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/{accountId}/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	accountId required	Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information.	string (uuid)

Body

Name	Description	Required	Schema
ownerCompanyName	The owner's company name.	Yes	string
ownerRegistrationNumber	The owner's registration number.	Yes	string
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 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	The algorithm that should be applied, can be either 1 for Privacy Id Header or 2 for Anonymous Invalid Header.	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 body

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

{
    "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/{accountId}/portingrequests

Parameters

Type	Name	Description	Schema
Path	accountId required	Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information.	string (uuid)
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

Response headers

Header	Description	Schema
Content-Type	application/json	-
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/{accountId}/portingrequests/{orderId}

Parameters

Type	Name	Description	Schema
Path	accountId required	Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information.	string (uuid)
Path	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

Response headers

Header	Description	Schema
Content-Type	application/json	-

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": 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/{accountId}/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	accountId required	Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information.	string (uuid)
Path	orderId required	Unique identifier of the number porting request order, this can be found in your confirmation email or the Voice Management App.	string

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 body

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

Response

200 OK

{
    "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/{accountId}/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	accountId required	Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information.	string (uuid)
Path	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

Response headers

Header	Description	Schema
Content-Type	application/json	-

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/{accountId}/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	accountId required	Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information.	string (uuid)
Path	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

Response headers

Header	Description	Schema
Content-Type	application/json	-

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/{accountId}/inboundnumbers?skip=0&take=10

Parameters

Type	Name	Description	Schema
Path	accountId required	Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information.	string (uuid)
Query	skip	Amount of items to skip. Minimum value is 0.	number
Query	take required	Amount of items to retrieve. Minimum value is 1.	number

Response

Response headers

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

Response body

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

Example response

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

Export phone numbers to Excel

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

Parameters

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

Response

Response headers

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

Response body

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

Phone number configurations

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

No configuration

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

SIP configuration

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

Notification configuration

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

Direct forwarding configuration

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

Update phone number configurations

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

Body

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

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

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

Example body

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

Response

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

Response body

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

Example response

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

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/{accountId}/phonenumbers/{phonenumber}/customeralias

Parameters

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

Body

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

{
    "customerAlias": string
}

Example body

{
  "customerAlias": "Custom alias"
}

Response

200 OK

[
  {
    "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/{accountId}/distributiongroups

Parameters

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

Body

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

Endpoint

Name	Description	Required	Schema
name	The name of the Endpoint.	Yes	string
ipAddress	The external IP Address of the Endpoint.	Yes	string
port	The port to be configured that is supported by CM. Supported ports: 5060-5100.	Yes	number
priority	Determines the Round-Robin order of the Endpoint. Each endpoint inside a Distribution Group must have a unique priority.	Yes	number
isActive	Determines whether the Endpoint should be active or not.	Yes	boolean

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

Response

201 Created

Response headers

Header	Description	Schema
Location	https://api.cm.com/voice-distributiongroupsapi/v1/{accountId}/distributiongroups/{distributionGroupGuid}	-

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

Example response

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

Get Distribution Groups

Get Distribution Groups that are linked to the specified Account.

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

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

Example response

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

Get Distribution Group

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

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

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

Example response

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

Update Distribution Group

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

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

Parameters

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

Body

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

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

Response

204 No Content

Delete Distribution Group

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

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

Parameters

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

Response

204 No Content

Create Endpoint(s)

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

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

Parameters

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

Body

See Endpoint for the definition.

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

Response

204 No Content

Get Endpoints

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

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

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

Example response

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

Get Endpoint

Get an Endpoint for the specified Account, Distribution Group identifier and Endpoint identifier.

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

Parameters

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

Response

Response headers

Header	Description	Schema
Content-Type	application/json	-

Response body

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

Example response

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

Update Endpoint

Updates a single Endpoint for the specified Account and identifiers.

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

Parameters

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

Body

See Endpoint for the definition.

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

Response

204 No Content

Delete Endpoint

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

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

Parameters

Type	Name	Description	Schema
Path	accountId required	Your account identifier. This can be either a Voice Account Id, or your Account Id. See Authentication for more information.	string (uuid)
Path	distributionGroupGuid required	Unique identifier of the Distribution Group.	string (uuid)
Path	endpointGuid required	Unique 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/{voiceAccountId}/conversations

Parameters

Type	Name	Description	Schema
Path	voiceAccountId required	Your voice account identifier.	string (uuid)
Query	skip	Amount of items to skip. Minimum value is 0.	number
Query	take required	Amount of items to retrieve. Minimum value is 1.	number
Query	from required	The timestamp indicating the start date.	DateTime Supported formats: yyyy-MM-ddTHH:mm:ss yyyy-MM-dd MM-dd-yyyy
Query	to required	The timestamp indicating the exclusive end date. Maximum range is 1 week.	DateTime Supported formats: yyyy-MM-ddTHH:mm:ss yyyy-MM-dd MM-dd-yyyy

Response

Response headers

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

Response body

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

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

Example response

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