{
  1. Introduction
    1. Authentication
    2. Getting your Account ID
  2. Keyword claims
    1. Claim a keyword
    2. Get your claimed keywords
    3. Get a keyword claim by id
    4. Cancel a keyword claim
    5. Verify a claim
  3. Dedicated phone numbers
    1. Request a phone number
    2. Get your phone number requests
    3. Cancel phone number ownership
    4. Get available phone numbers
    5. Get an available phone number by id
    6. Get available phone number types
  4. API Model definitions
    1. Keyword claims
      1. ApiKeywordClaimRequest
      2. ApiKeywordClaimResponse
    2. Dedicated phone numbers
      1. ApiNumberRequestResponse
      2. ApiPhoneNumberResponse
      3. ApiNumberTypeResponse

Introduction

This numbers API allows you to request ownership of CM.com's numbers, which you can use in your own systems.
You need phone numbers to enable your customers to communicate with you. May this be via SMS, WhatsApp, Viber or phone calls.
Via this API call you can request a number from CM.com, without the need of a SIM card, or having a physical phone.
Once requested CM.com automatically configures your number and allows you to use it for incoming traffic your receive from your customers, and or employees.

You are sending in a request for a number to CM.com, depending on the availability of numbers we have on our shelves they will be provided right away. Or shared with you once we have enabled it.

You can request various number types via this API:

  1. Keywords on shared numbers
  2. Dedicated long numbers

When you want to request a dedicated short code, please contact our support teams.

Authentication

Authentication and authorization is done via a product token. You can obtain your product token from the messaging gateway app (https://gateway.cmtelecom.com). If you don't see that app you might have got it via your account manager or you can contact support to obtain one.

For all methods described in this API, the product token should be provided by including it in the X-CM-PRODUCTTOKEN header.

Getting your Account ID

In all methods you need to provide the accountId. This is a guid that identifies your account.
This identifier can be found on the url of CM.com's platform applications, after the language indicator. Below you can find an example.

Url AccountID
https://www.cm.com/en-gb/app/dashboard/a66b6ba2-7b13-4caf-abf6-c736c977c1d4 a66b6ba2-7b13-4caf-abf6-c736c977c1d4



Keyword claims

Claim a keyword on a shared or dedicated (owned) number.

Claim a keyword

Claim a keyword. (Or simulate the outcome)

POST https://api.cmtelecom.com/numbers/v1/accounts/{accountId}/keywords

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. string (uuid)
Query simulate
optional
If set to true no actual operations will be performed, but validation will occur. boolean
Body claim
required
The claim. ApiKeywordClaimRequest

Responses

HTTP Code Description Schema
201 Created ApiKeywordClaimResponse

Example HTTP request

Request path

POST https://api.cmtelecom.com/numbers/v1/accounts/00000000-0000-0000-0000-000000000000/keywords&simulate=true

Request body

{
  "phoneNumber": "0000000000",
  "keyword": "KEYWORD"
}

Response body (200)

{
  "id": "00000000-0000-0000-0000-000000000000",
  "phoneNumber": "0000000000",
  "country": "NL",
  "keyword": "string",
  "currency": "EUR",
  "startupCost": 0,
  "monthlyCost": 0,
  "claimedOnUtc": "2019-01-31T10:39:16.197Z"
}

Get your claimed keywords

This call is used to get all claimed keywords you have registered with CM.com and their status.

GET https://api.cmtelecom.com/numbers/v1/accounts/{accountId}/keywords

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. string (uuid)
Query phoneNumber
optional
The phone numbers to filter the results on. array[string]
Query keyword
optional
The keywords to filter the results on. array[string]
Query country
optional
The country to filter the results on. string
Query skip
optional
The amount of results to skip. (pagination) integer
Query take
optional
The amount of results to take. (pagination) integer

Responses

HTTP Code Description Schema
200 OK array[ApiKeywordClaimResponse]

Example HTTP request

Request path

GET https://api.cmtelecom.com/numbers/v1/accounts/00000000-0000-0000-0000-000000000000/keywords

Response body (200)

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "phoneNumber": "0000000000",
    "country": "NL",
    "keyword": "string",
    "currency": "EUR",
    "startupCost": 0,
    "monthlyCost": 0,
    "claimedOnUtc": "2019-01-31T10:39:16.197Z"
  }
]

Get a keyword claim by id

When you require to know the status of a keyword claim, you can request that too.
You can do this by implementing this call.

GET https://api.cmtelecom.com/numbers/v1/accounts/{accountId}/keywords/{keywordClaimId}

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. string (uuid)
Path keywordClaimId
required
The claim identifier. string (uuid)

Responses

HTTP Code Description Schema
200 OK ApiKeywordClaimResponse

Example HTTP request

Request path

GET https://api.cmtelecom.com/numbers/v1/accounts/00000000-0000-0000-0000-000000000000/keywords/00000000-0000-0000-0000-000000000000

Response body (200)

{
  "id": "00000000-0000-0000-0000-000000000000",
  "phoneNumber": "0000000000",
  "country": "NL",
  "keyword": "string",
  "currency": "EUR",
  "startupCost": 0,
  "monthlyCost": 0,
  "claimedOnUtc": "2019-01-31T10:39:16.197Z"
}

Cancel a keyword claim

If you make use of a keyword you no longer need, you can cancel the claim.
Your invoicing will be stopped coming invoicing month, which means you only need to pay for the current month.
Right after you cancel your keyword subscription this can no longer be used by you, we block it right away and do not await the end of your monthly subscription.

DELETE https://api.cmtelecom.com/numbers/v1/accounts/{accountId}/keywords/{keywordClaimId}

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. string (uuid)
Path keywordClaimId
required
The claim identifier. string (uuid)

Responses

HTTP Code Description Schema
204 NoContent

Example HTTP request

Request path

DELETE https://api.cmtelecom.com/numbers/v1/accounts/00000000-0000-0000-0000-000000000000/keywords/00000000-0000-0000-0000-000000000000

Verify a claim

Verifies a claim by id and returns an array of strings describing found issues.

GET https://api.cmtelecom.com/numbers/v1/accounts/{accountId}/keywords/{keywordClaimId}/verify

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. string (uuid)
Path keywordClaimId
required
The claim identifier. string (uuid)

Responses

HTTP Code Description Schema
200 OK array[string]

Example HTTP request

Request path

GET https://api.cmtelecom.com/numbers/v1/accounts/00000000-0000-0000-0000-000000000000/keywords/00000000-0000-0000-0000-000000000000/verify

Response body (200)

[
  "string"
]



Dedicated phone numbers

Rent a dedicated phone number.

Request a phone number

Request to rent a dedicated phone number. (Or simulate the outcome)

POST https://api.cmtelecom.com/numbers/v1/accounts/{accountId}/phonenumbers/requests

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. string (uuid)
Query numberTypeId
required
The number type identifier. string (uuid)
Query simulate
optional
If set to true no actual operations will be performed, but validation will occur. boolean

Responses

HTTP Code Description Schema
201 Created ApiNumberRequestResponse

Example HTTP request

Request path

POST https://api.cmtelecom.com/numbers/v1/accounts/00000000-0000-0000-0000-000000000000/phonenumbers/requests?numberTypeId=00000000-0000-0000-0000-000000000000&simulate=true

Response body (200)

{
  "id": "00000000-0000-0000-0000-000000000000",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "numberType": 
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "purpose": "SMS",
    "country": "NL",
    "type": "MOBILE",
    "currency": "EUR",
    "startupCost": 0,
    "monthlyCost": 0,
    "noticePeriodDays": 0,
    "keywordStartupCost": 0,
    "keywordMonthlyCost": 0,
    "keywordNoticePeriodDays": 0,
    "numberRequestProcessingDays": 0
  },
  "isPending": true,
  "createdOnUtc": "2019-01-31T10:39:16.241Z"
}

Get your phone number requests

This call is used to get all your phone number requests registered with CM.com and their status.

GET https://api.cmtelecom.com/numbers/v1/accounts/{accountId}/phonenumbers/requests

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. string (uuid)
Query country
optional
The country to filter the results on. string
Query isPending
optional
If set, filters the result on pending state. boolean
Query skip
optional
The amount of results to skip. (pagination) integer
Query take
optional
The amount of results to take. (pagination) integer

Responses

HTTP Code Description Schema
200 OK array[ApiNumberRequestResponse]

Example HTTP request

Request path

GET https://api.cmtelecom.com/numbers/v1/accounts/00000000-0000-0000-0000-000000000000/phonenumbers/requests?country=NL&isPending=true&skip=0&take=1

Response body (200)

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "phoneNumberId": "0000000000",
    "numberType": 
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "purpose": "SMS",
      "country": "NL",
      "type": "MOBILE",
      "currency": "EUR",
      "startupCost": 0,
      "monthlyCost": 0,
      "noticePeriodDays": 0,
      "keywordStartupCost": 0,
      "keywordMonthlyCost": 0,
      "keywordNoticePeriodDays": 0,
      "numberRequestProcessingDays": 0
    },
    "isPending": false,
    "createdOnUtc": "2019-01-31T11:39:16.241Z"
  }
]

Cancel a phone number subscription

If you rent a phone numbers you no longer need, you can cancel the subscription.
Your invoicing will be stopped coming invoicing month, which means you only need to pay for the current month.
Right after you cancel your phone number subscription this can no longer be used by you, we block it right away and do not await the end of your monthly subscription.

DELETE https://api.cmtelecom.com/numbers/v1/accounts/{accountId}/phonenumbers/{phoneNumberId}

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. string (uuid)
Path phoneNumberId
required
The phone number identifier. string (uuid)

Responses

HTTP Code Description Schema
204 NoContent

Example HTTP request

Request path

DELETE https://api.cmtelecom.com/numbers/v1/accounts/00000000-0000-0000-0000-000000000000/phonenumbers/0000000000

Get available phone numbers

This call is used to get all available phone numbers registered with CM.com.
Only shared (for claiming a keyword on) and owned phone numbers are returned.

GET https://api.cmtelecom.com/numbers/v1/accounts/{accountId}/phonenumbers

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. string (uuid)
Query query
optional
The query to search for and filter the results on. string
Query country
optional
The country to filter the results on. string
Query isOwned
optional
If set, result is filtered on whether a phone number is/is not owned by you. boolean
Query isShortcode
optional
If set, result is filtered on whether a phone number is/is not a shortcode. boolean
Query isShared
optional
If set, result is filtered on whether a phone number is/is not a shared number. boolean
Query skip
optional
The amount of results to skip. (pagination) integer
Query take
optional
The amount of results to take. (pagination) integer

Responses

HTTP Code Description Schema
200 OK array[ApiPhoneNumberResponse]

Example HTTP request

Request path

GET https://api.cmtelecom.com/numbers/v1/accounts/00000000-0000-0000-0000-000000000000/phonenumbers?query=0000&country=NL&isOwned=true&isShortcode=false&isShared=false&skip=0&take=1

Response body (200)

[
  {
    "id": "0000000000",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "numberType":
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "purpose": "SMS",
      "country": "NL",
      "type": "MOBILE",
      "currency": "EUR",
      "startupCost": 0,
      "monthlyCost": 0,
      "noticePeriodDays": 0,
      "keywordStartupCost": 0,
      "keywordMonthlyCost": 0,
      "keywordNoticePeriodDays": 0,
      "numberRequestProcessingDays": 0
    },
    "number": "0000000000",
    "isShared": false,
    "ownedSinceUtc": "2019-02-05T12:34:08.614Z"
  }
]

Get an available phone number by id

When you require to know the status of a phone number, you can request that too.
You can do this by implementing this call.
Only shared (for claiming a keyword on) and owned phone numbers are returned.

GET https://api.cmtelecom.com/numbers/v1/accounts/{accountId}/phonenumbers/{phoneNumberId}

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. string (uuid)
Path phoneNumberId
required
The phone number identifier. string (uuid)

Responses

HTTP Code Description Schema
200 OK ApiPhoneNumberResponse

Example HTTP request

Request path

GET https://api.cmtelecom.com/numbers/v1/accounts/00000000-0000-0000-0000-000000000000//phonenumbers/0000000000

Response body (200)

{
  "id": "0000000000",
  "numberType": 
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "purpose": "SMS",
    "country": "NL",
    "type": "MOBILE",
    "currency": "EUR",
    "startupCost": 0,
    "monthlyCost": 0,
    "noticePeriodDays": 0,
    "keywordStartupCost": 0,
    "keywordMonthlyCost": 0,
    "keywordNoticePeriodDays": 0,
    "numberRequestProcessingDays": 0
  },
  "number": "0000000000",
  "isShared": true
}

Get available phone number types

This call is used to get all available number types registered with CM.com.
Number types are linked to phone numbers and are mandatory in requesting a dedicated phone number.

GET https://api.cmtelecom.com/numbers/v1/accounts/{accountId}/phonenumbers/numbertypes

Parameters

Type Name Description Schema
Path accountId
required
Your account identifier. string (uuid)
Query country
optional
The country to filter the results on. string
Query type
optional
The type to filter the results on. string
Query purpose
optional
The purpose to filter the results on. string
Query skip
optional
The amount of results to skip. (pagination) integer
Query take
optional
The amount of results to take. (pagination) integer

Responses

HTTP Code Description Schema
200 OK array[ApiNumberTypeResponse]

Example HTTP request

Request path

GET https://api.cmtelecom.com/numbers/v1/accounts/00000000-0000-0000-0000-000000000000/phonenumbers?country=NL&isOwned=true&isShortcode=false&isShared=false&skip=0&take=1

Response body (200)

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "purpose": "SMS",
    "country": "NL",
    "type": "MOBILE",
    "currency": "EUR",
    "startupCost": 0,
    "monthlyCost": 0,
    "noticePeriodDays": 0,
    "keywordStartupCost": 0,
    "keywordMonthlyCost": 0,
    "keywordNoticePeriodDays": 0,
    "numberRequestProcessingDays": 0
  }
]



Model Definitions

Definitions of Numbers API specific request and response data models.
This includes names, types, descriptions and a JSON representation.


Keyword claims

Models used at keyword claiming related endpoints.


ApiKeywordClaimRequest

Model
Name Schema Description
phoneNumber
required
string The phone number on which the keyword is about to be claimed on.
keyword
required
string The keyword that is about to be claimed.
JSON
{
  "phoneNumber": "0000000000",
  "keyword": "KEYWORD"
}


ApiKeywordClaimResponse

Model
Name Schema Description
id string The identifier of the claim.
phoneNumber string The phone number on which the claim is active on.
keyword string The keyword on which the claim is active on.
country string The country in ISO 3166-2 notation.
currency string The currency in the ISO 4217 notation.
startupCost integer The startup cost.
monthlyCost integer The monthly cost.
claimedOnUtc string The moment (UTC) the claim went active.
JSON
{
  "id": "00000000-0000-0000-0000-000000000000",
  "phoneNumber": "0000000000",
  "country": "NL",
  "keyword": "KEYWORD",
  "currency": "EUR",
  "startupCost": 0,
  "monthlyCost": 0,
  "claimedOnUtc": "2019-03-18T09:56:31.723Z"
}


Dedicated phone numbers

Models used at dedicated phone number related endpoints.


ApiNumberRequestResponse

Model
Name Schema Description
id string (uuid) The number request identifier.
accountId string (uuid) The account this request belongs to.
phoneNumberId
optional
string The phone number identifier. Is only set/returned when request is fulfilled/not pending.
numberType ApiNumberTypeResponse The type of number.
isPending boolean Indicates whether this request is pending. A request is pending when a suitable number is not immediately available.
fulfilledOnUtc timestamp (UTC) The moment (UTC) the request was fulfilled.
createdOnUtc timestamp (UTC) The moment (UTC) the request was created.
JSON
{
  "id": "00000000-0000-0000-0000-000000000000",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "phoneNumberId": "0000000000",
  "numberType": 
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "purpose": "SMS",
    "country": "NL",
    "type": "MOBILE",
    "currency": "EUR",
    "startupCost": 0,
    "monthlyCost": 0,
    "noticePeriodDays": 0,
    "keywordStartupCost": 0,
    "keywordMonthlyCost": 0,
    "keywordNoticePeriodDays": 0,
    "numberRequestProcessingDays": 0
  },
  "isPending": true,
  "fulfilledOnUtc": "2019-03-18T09:56:31.764Z",
  "createdOnUtc": "2019-01-31T10:39:16.241Z"
}


ApiPhoneNumberResponse

Model
Name Schema Description
id string (uuid) The phone number identifier.
accountId
optional
string (uuid) The account this phone number is owned by. Is only returned to the account that owns the number.
numberType ApiNumberTypeResponse The type of number.
number string The phone number in international format with a "00" prefix.
isShared boolean True if this number can be shared by multiple customers.
ownedSinceUtc timestamp (UTC) The moment (UTC) since the number is in possession. Is only returned to the account that owns the number.
JSON
{
  "id": "0000000000",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "numberType": 
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "purpose": "SMS",
    "country": "NL",
    "type": "MOBILE",
    "currency": "EUR",
    "startupCost": 0,
    "monthlyCost": 0,
    "noticePeriodDays": 0,
    "keywordStartupCost": 0,
    "keywordMonthlyCost": 0,
    "keywordNoticePeriodDays": 0,
    "numberRequestProcessingDays": 0
  },
  "number": "0000000000",
  "isShared": false,
  "ownedSinceUtc": "2019-02-05T12:34:08.614Z"
}


ApiNumberTypeResponse

Model
Name Schema Description
id string (uuid) The number type identifier.
purpose string The purpose of the number.
country string The country in ISO 3166-2 notation.
type string The type.
currency string The currency in the ISO 4217 notation.
startupCost double The initial cost when renting a dedicated number of this type.
monthlyCost double The cost per month when renting a dedicated number of this type.
noticePeriodDays integer The notice period in days when renting a dedicated number of this type.
keywordStartupCost double The initial cost when claiming a keyword on a shared number of this type.
keywordMonthlyCost double The cost per month per claimed keyword on a shared number of this type.
keywordNoticePeriodDays integer The notice period in days for a claimed keyword on a shared number of this type.
numberRequestProcessingDays integer The processing time in days to fulfill the request of an unavailable dedicated number of this type.
JSON
{
  "id": "00000000-0000-0000-0000-000000000000",
  "purpose": "SMS",
  "country": "NL",
  "type": "MOBILE",
  "currency": "EUR",
  "startupCost": 0,
  "monthlyCost": 0,
  "noticePeriodDays": 0,
  "keywordStartupCost": 0,
  "keywordMonthlyCost": 0,
  "keywordNoticePeriodDays": 0,
  "numberRequestProcessingDays": 0
}