CM's Addressbook v2 API enables you to store your groups of recipients. You can integrate this in your application by communicating with our api.
The Addressbook API is a REST API that uses JSON to communicate.
Authentication and authorization is done via a product token. You can obtain your product token from the messaging gateway app (https://cm.com/app/gateway). 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.
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 the addressbook application (https://cm.com/app/addressbook), after the language indicator. Below you can find some url examples and the corresponding accountID.
Url | AccountID |
---|---|
https://cm.com/en/app/addressbook/a66b6ba2-7b13-4caf-abf6-c736c977c1d4 | a66b6ba2-7b13-4caf-abf6-c736c977c1d4 |
https://cm.com/en/app/addressbook/fe266716-d8ff-4aba-bddb-c61f8f40c656/Templates | fe266716-d8ff-4aba-bddb-c61f8f40c656 |
POST https://api.cm.com/addressbook/v2/accounts/{accountId}/groups
Example post body:
{ "name": "QuickStart" }
Example curl request :
curl -X POST \ https://api.cm.com/addressbook/v2/accounts/z9761684-b8d0-440f-8508-72ec36766069/groups \ -H 'Accept: application/json, text/json' \ -H 'Content-Type: application/json' \ -H 'X-CM-PRODUCTTOKEN: ce4e6c52-5696-405b-9524-e478468f1907' \ -d '{ "name": "QuickStart", }'
POST https://api.cm.com/addressbook/v2/accounts/{accountId}/groups/{groupId}/contacts
Example post body:
{ "firstName": "John", "insertion": "van", "lastName": "Doe", "email": "[email protected]", "phoneNumber": "+31627100000", "groupId": "95ac8e9b-9de3-4e2b-ae18-23786f99d3a8", "customValues": [ { "fieldId": 6, "value": "Test Company" } ] }
Example curl request :
curl -X POST \ https://api.cm.com/addressbook/v2/accounts/z9761684-b8d0-440f-8508-72ec36766069/groups/95ac8e9b-9de3-4e2b-ae18-23786f99d3a8/contacts \ -H 'Accept: application/json, text/json' \ -H 'Content-Type: application/json' \ -H 'X-CM-PRODUCTTOKEN: ce4e6c52-5696-405b-9524-e478468f1907' \ -d '{ "firstName": "John", "insertion": "van", "lastName": "Doe", "email": "[email protected]", "phoneNumber": "+31627100000", "customValues": [ { "fieldId": 6, "value": "Test Company" } ] }'
Please refer to relative sections for information.
We have recently released a new version (v2) of the Addressbook API. Although it is mostly backwards compatible (old api calls are documented in https://docs.cmtelecom.com/address-book/v1.0), we suggest new applications to use v2 endpoints for the future.
In Addressbook each contact can be in a single group, also contacts has a customValues property which includes all the extra data as a json object.
Name | Description | Schema |
---|---|---|
createdOnUtc optional |
string (date-time) | |
customValues optional |
< CustomValue > array | |
email optional |
string | |
firstName optional |
string | |
groupId |
Example : "00000000-0000-0000-0000-000000000000" |
string (uuid) |
id optional |
Example : "00000000-0000-0000-0000-000000000000" |
string (uuid) |
insertion optional |
string | |
isUnsubscribed optional |
only available when using Dump endpoint | string |
lastName optional |
string | |
phoneCountry optional |
string | |
phoneNumber optional |
string |
Name | Schema |
---|---|
fieldId optional |
integer (int32) |
value optional |
string |
For backwards compatibility there are predefined fieldIds for old CustomFields data.
Name | FieldId |
---|---|
Company | 6 |
CustomField1 | 7 |
CustomField2 | 8 |
CustomField3 | 9 |
CustomField4 | 10 |
CustomField5 | 11 |
CustomField6 | 12 |
CustomField7 | 13 |
CustomField8 | 14 |
CustomField9 | 15 |
CustomField10 | 16 |
POST https://api.cm.com/addressbook/v2/accounts/{accountId}/groups/{groupId}/contacts
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The guid of the account. | string (uuid) |
Path | groupId required |
string (uuid) | |
Body | contact required |
The name of the group. | Contact |
HTTP Code | Description | Schema |
---|---|---|
201 | Created | Contact |
POST https://api.cm.com/addressbook/v2/accounts/{accountId}/groups/{groupId}/contacts-bulk
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Path | groupId required |
string (uuid) | |
Query | delayIndexing optional |
If set to true it doesnt start indexing the group contacts immediately. | boolean |
Body | contacts required |
The contacts. | < Contact > array |
Indexing is necessary to be able to search for contacts but indexing while importing items takes more time. When importing a marketing list to be used once, suggested delayIndexing value is true. So that we can process your imports faster.
While importing a large (<10k) amount of contacts we suggest setting delayIndexing to true for initial batches and set it to false on the last batch or make an extra call with no contacts in the body with delayIndexing set to false.
We suggest api users to limit their batches to 2.5k at a time.
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/contacts/{contactId}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Path | contactId required |
The contact guid. | string (uuid) |
Query | optOutTokenType optional |
The optout token type. | string |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | Contact |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/groups/{groupId}/contacts
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The accountId. | string (uuid) |
Path | groupId required |
The group id to fetch | string (uuid) |
Query | getCustomValues optional |
If set true fetches custom values for the contact. | boolean |
Query | optOutTokenType optional |
If set true filters results by OptOut tokentype. | string |
Query | orderBy optional |
Orders contacts by name or creation date. Use desc (date desc) to order descending | string |
Query | skip optional |
The skip. | integer (int32) |
Query | take optional |
The take. | integer (int32) |
PUT https://api.cm.com/addressbook/v2/accounts/{accountId}/contacts/{contactId}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The owner account identifier. | string (uuid) |
Path | contactId required |
The contact id | string (uuid) |
Body | contact required |
The group. | Contact |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | Contact |
DELETE https://api.cm.com/addressbook/v2/accounts/{accountId}/contacts/{contactId}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The owner account identifier. | string (uuid) |
Path | contactId required |
The identifier. | string (uuid) |
DELETE https://api.cm.com/addressbook/v2/accounts/{accountId}/contacts
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The owner account identifier. | string (uuid) |
Query | contactIds required |
The identifier. | < string (uuid) > array(multi) |
HTTP Code | Description | Schema |
---|---|---|
204 | NoContent | No Content |
Name | Description | Schema |
---|---|---|
bypassOptOut optional |
boolean | |
contactsAmount optional |
integer (int32) | |
emptyEmails optional |
number of contacts without emails | integer (int32) |
emptyNumbers optional |
number of contacts without phone numbers | integer (int32) |
createdOnUtc optional |
string (date-time) | |
id optional |
Example : "00000000-0000-0000-0000-000000000000" |
string (uuid) |
isFavorite optional |
boolean | |
isHidden optional |
boolean | |
isLockedForEditing optional |
boolean | |
isLockedForSending optional |
boolean | |
name optional |
string |
POST https://api.cm.com/addressbook/v2/accounts/{accountId}/groups
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The guid of the account. | string (uuid) |
Body | group required |
The name of the group. | Group |
HTTP Code | Description | Schema |
---|---|---|
201 | Created | ApiGroup |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/groups/{groupId}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Path | groupId required |
The group guid. | string (uuid) |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/groups
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The accountId. | string (uuid) |
Query | favorite optional |
If set true fetches only favorite groups. | boolean |
Query | includeHidden optional |
If set true fetches also hidden groups. | boolean |
Query | orderBy optional |
Orders groups by column names such as name, contacts or creation date. use desc (date desc) to order descending | string |
Query | skip optional |
The skip. | integer (int32) |
Query | take optional |
The take. | integer (int32) |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < Group > array |
PUT https://api.cm.com/addressbook/v2/accounts/{accountId}/groups/{groupId}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The owner account identifier. | string (uuid) |
Path | groupId required |
string (uuid) | |
Body | group required |
The group. | Group |
DELETE https://api.cm.com/addressbook/v2/accounts/{accountId}/groups/{groupId}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The owner account identifier. | string (uuid) |
Path | groupId required |
The identifier. | string (uuid) |
HTTP Code | Description | Schema |
---|---|---|
204 | NoContent | No Content |
DELETE https://api.cm.com/addressbook/v2/accounts/{accountId}/groups
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The owner account identifier. | string (uuid) |
Query | groupIds required |
The identifiers. | < string (uuid) > array(multi) |
HTTP Code | Description | Schema |
---|---|---|
204 | NoContent | No Content |
DELETE https://api.cm.com/addressbook/v2/accounts/{accountId}/groups/{groupId}/contacts
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Path | groupId required |
The group guid. | string (uuid) |
Fields define the labels for customValues that are stored with the contacts
Name | Schema |
---|---|
id optional |
integer (int32) |
name optional |
string |
POST https://api.cm.com/addressbook/v2/accounts/{accountId}/fields
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The guid of the account. | string (uuid) |
Body | field required |
The field. | Field |
HTTP Code | Description | Schema |
---|---|---|
201 | Created | Field |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/fields/{fieldId}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Path | fieldId required |
The field id. | integer (int32) |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/fields
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The accountId. | string (uuid) |
PUT https://api.cm.com/addressbook/v2/accounts/{accountId}/fields/{fieldId}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account identifier. | string (uuid) |
Path | fieldId required |
The fieldId. | integer (int32) |
Body | field required |
The field. | Field |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | Field |
DELETE https://api.cm.com/addressbook/v2/accounts/{accountId}/fields/{fieldId}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account identifier. | string (uuid) |
Path | fieldId required |
The identifier. | integer (int32) |
HTTP Code | Description | Schema |
---|---|---|
204 | NoContent | No Content |
Opt-Out management enables users to Opt-Out/Opt-In from receiving messages/emails from organizations.
Opt-Out lists are stored for organizations based on token type, currently “email” or “sms” (more channels can be added).
While sending emails/messages receipent lists should be filtered to not include emails/phonenumbers that are opted out.
Opt-Out Management system keeps a Opt-Out History for each email address or phone number, so that one can see when a specific email/sms contact Opted Out/In.
Opt-Out Management is fully integrated with Addressbook v2 API, so that Addressbook v2 API can provide Opt-Out filtered list of contacts/groups for email/sms campaigns or for any other usage.
Specific groups (like employee groups) can be by passed from Opt-Out filters so that all contacts in these groups receive messages/emails even if they Opt-Out.
Also third-party applications can retrieve/use Opt-Out lists based on token types and can use Opt-Out lists as they need.
Name | Schema |
---|---|
isActive optional |
boolean |
type optional |
string |
value optional |
string |
POST https://api.cm.com/addressbook/v2/accounts/{accountId}/optout/{tokenType}/{tokenValue}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Path | tokenType required |
The token type. | string |
Path | tokenValue required |
The token value. | string |
Body | message required |
The optOutHistory message. | OptOutHistoryInput |
*** message must be in json format. Ex: { "message": "string" }
HTTP Code | Description | Schema |
---|---|---|
200 | OK | OptOut |
POST https://api.cm.com/addressbook/v2/accounts/{accountId}/optout/bulk
If IsActive property of OptOut objects are set to true, then it is considered as an OptOut. If IsActive property of OptOut objects are set to false, then it is considered as an OptIn (delete).
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Query | message required |
The optOutHistory message. | string |
Body | tokens required |
The optout tokens. | < OptOut > array |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | integer (int32) |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/optout/{tokenType}/{tokenValue}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Path | tokenType required |
The token type. | string |
Path | tokenValue required |
The token value. | string |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | OptOut |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/optout
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Query | skip optional |
The skip. | integer (int32) |
Query | take optional |
The take. | integer (int32) |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | OptOut |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/optout/{tokenType}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Path | tokenType required |
The token type. | string |
Query | isActive optional |
If set to false fetches optins | boolean |
Query | skip optional |
integer (int32) | |
Query | take optional |
integer (int32) |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < OptOut > array |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/optout/types
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < ApiTokenType > array |
Name | Schema |
---|---|
amountOptIn optional |
integer (int32) |
amountOptOut optional |
integer (int32) |
description optional |
string |
id optional |
string |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/optout/{tokenType}/{tokenValue}/history
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Path | tokenType required |
The token type. | string |
Path | tokenValue required |
The token value. | string |
Query | skip optional |
integer (int32) | |
Query | take optional |
integer (int32) |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < OptOutHistory > array |
Name | Description | Schema |
---|---|---|
createdBy optional |
Example : "00000000-0000-0000-0000-000000000000" |
string (uuid) |
createdOnUtc optional |
string (date-time) | |
isActive optional |
boolean | |
message optional |
string |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/optout/search
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Query | q required |
The query. | string |
Query | skip optional |
The skip. | integer (int32) |
Query | take optional |
The take. | integer (int32) |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | OptOut |
DELETE https://api.cm.com/addressbook/v2/accounts/{accountId}/optout/{tokenType}/{tokenValue}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The guid of the account. | string (uuid) |
Path | tokenType required |
The token type. | string |
Path | tokenValue required |
The token value. | string |
Body | message required |
The optOutHistory message. | OptOutHistoryInput |
*** message must be in json format. Ex: { "message": "string" }
HTTP Code | Description | Schema |
---|---|---|
200 | OK | OptOut |
Dump endpoints provides OptOut filtered list of contacts as a json array or CSV.
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/dump/
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Path | tokenType required |
The token type for the contacts. | string |
Query | groupIds required |
The groupIds. | < string (uuid) > array(multi) |
Query | contactIds required |
The contactIds. | < string (uuid) > array(multi) |
Query | lastGuid optional |
The Id of the last received contact to be used as a cursor. | string (uuid) |
Query | take optional |
The take. | int |
*** lastGuid acts as a cursor, instead of using an offset, using a cursor enables faster query performance regardless of the data size.
HTTP Code | Description | Schema |
---|---|---|
200 | OK | Contact |
Contacts are filtered by OptOut lists first then contacts returned are flagged using isUnsubscribed field.
Current available tokenTypes are sms or email.
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/dump/{tokenType}
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Path | tokenType required |
The token type for the contacts. | string |
Query | groupIds required |
The groupIds. | < string (uuid) > array(multi) |
Query | contactIds required |
The contactIds. | < string (uuid) > array(multi) |
Query | lastGuid optional |
The Id of the last received contact to be used as a cursor. | string (uuid) |
Query | take optional |
The take. | int |
*** lastGuid acts as a cursor, instead of using an offset, using a cursor enables faster query performance regardless of the data size.
HTTP Code | Description | Schema |
---|---|---|
200 | OK | Contact |
Contacts are returned in CSV format.
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/dump/csv
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Query | contactIds required |
The groupIds. | < string (uuid) > array(multi) |
Query | groupIds required |
The groupIds. | < string (uuid) > array(multi) |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | CSV File |
Contacts are filtered by OptOut lists first then only fields specified by the request are returned from the API in CSV format.
Current available tokenTypes are sms or email.
Below is the list of predefined fieldIds.
Name | FieldId |
---|---|
FirstName | 1 |
Insertion | 2 |
LastName | 3 |
PhoneNumber | 4 |
EmailAddress | 5 |
Company | 6 |
CustomField1 | 7 |
CustomField2 | 8 |
CustomField3 | 9 |
CustomField4 | 10 |
CustomField5 | 11 |
CustomField6 | 12 |
CustomField7 | 13 |
CustomField8 | 14 |
CustomField9 | 15 |
CustomField10 | 16 |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/dump/{tokenType}/csv
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Path | tokenType required |
The token type for the contacts. | string |
Query | fieldId optional |
The Id of the fields to be fetched. | < integer (int32) > array(multi) |
Query | groupIds required |
The groupIds. | < string (uuid) > array(multi) |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | CSV File |
Search object holds group or contact data.
Name | Description | Schema |
---|---|---|
bypassOptOut optional |
boolean | |
contactsAmount optional |
integer (int32) | |
emptyEmails optional |
number of contacts without emails | integer (int32) |
emptyNumbers optional |
number of contacts without phone numbers | integer (int32) |
createdOnUtc optional |
string (date-time) | |
email optional |
string | |
firstname optional |
string | |
groupId optional |
Example : "00000000-0000-0000-0000-000000000000" |
string (uuid) |
id optional |
Example : "00000000-0000-0000-0000-000000000000" |
string (uuid) |
insertion optional |
string | |
isFavorite optional |
boolean | |
isMarketing optional |
boolean | |
isGroupMarketing optional |
boolean | |
isHidden optional |
boolean | |
isLockedForEditing optional |
boolean | |
isLockedForSending optional |
boolean | |
lastname optional |
string | |
name optional |
string | |
groupName optional |
only returned with contacts | string |
phoneCountry optional |
string | |
phoneNumber optional |
string | |
type optional |
string |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/search
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Query | q required |
The query string. | string |
Query | excludeMarketingContacts optional |
Excludes contacts in marketing groups. | boolean |
Query | skip optional |
The skip. | integer (int32) |
Query | take optional |
The take. | integer (int32) |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | Search |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/search/groups
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Query | q required |
The query string. | string |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | Search |
GET https://api.cm.com/addressbook/v2/accounts/{accountId}/groups/{groupId}/search
Type | Name | Description | Schema |
---|---|---|---|
Path | accountId required |
The account guid. | string (uuid) |
Path | groupId required |
The groupId. | string (uuid) |
Query | q required |
The query string. | string |
HTTP Code | Description | Schema |
---|---|---|
200 | OK | Search |