Addressbook v2

Intro

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

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 accountID

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://addressbook.cmtelecom.com), after the language indicator. Below you can find some url examples and the corresponding accountID.

Url AccountID
https://addressbook.cmtelecom.com/en/a66b6ba2-7b13-4caf-abf6-c736c977c1d4 a66b6ba2-7b13-4caf-abf6-c736c977c1d4
https://addressbook.cmtest.nl/fr/fe266716-d8ff-4aba-bddb-c61f8f40c656#/Templates fe266716-d8ff-4aba-bddb-c61f8f40c656

Getting started

How to create a group:

POST https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/groups

Example post body: { "name": "QuickStart" }

Example curl request : curl -X POST \ https://api.cmtelecom.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", }'

How to create a contact:

POST https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/groups/{groupId}/contacts

Example post body: { "firstName": "John", "insertion": "van", "lastName": "Doe", "email": "john.doe@example.com", "phoneNumber": "+31627100000", "groupId": "95ac8e9b-9de3-4e2b-ae18-23786f99d3a8", "customValues": [ { "fieldId": 6, "value": "Test Company" } ] }

Example curl request : curl -X POST \ https://api.cmtelecom.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": "john.doe@example.com", "phoneNumber": "+31627100000", "customValues": [ { "fieldId": 6, "value": "Test Company" } ] }'

Please refer to relative sections for information.

BackwardsCompatibility

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.

Contacts

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
lastName
optional
string
phoneCountry
optional
string
phoneNumber
optional
string

CustomValue

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

Adds a contact.

POST https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/groups/{groupId}/contacts

Parameters

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

Responses

HTTP Code Description Schema
201 Created Contact

Add multiple contacts at once.

POST https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/groups/{groupId}/contacts-bulk

Parameters

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.

Gets a contact by guid.

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/contacts/{contactId}

Parameters

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

Responses

HTTP Code Description Schema
200 OK Contact

Gets contacts within a group

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/groups/{groupId}/contacts

Parameters

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)

Updates a contact.

PUT https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/contacts/{contactId}

Parameters

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

Responses

HTTP Code Description Schema
200 OK Contact

Group

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

Adds a group.

POST https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/groups

Parameters

Type Name Description Schema
Path accountId
required
The guid of the account. string (uuid)
Body group
required
The name of the group. Group

Responses

HTTP Code Description Schema
201 Created ApiGroup

Gets a group by guid.

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/groups/{groupId}

Parameters

Type Name Description Schema
Path accountId
required
The account guid. string (uuid)
Path groupId
required
The group guid. string (uuid)

Gets Groups paged.

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/groups

Parameters

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)

Responses

HTTP Code Description Schema
200 OK < Group > array

Updates a group.

PUT https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/groups/{groupId}

Parameters

Type Name Description Schema
Path accountId
required
The owner account identifier. string (uuid)
Path groupId
required
string (uuid)
Body group
required
The group. Group

Deletes a group.

DELETE https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/groups/{groupId}

Parameters

Type Name Description Schema
Path accountId
required
The owner account identifier. string (uuid)
Path groupId
required
The identifier. string (uuid)

Responses

HTTP Code Description Schema
204 NoContent No Content

Deletes groups with provided guids.

DELETE https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/groups

Parameters

Type Name Description Schema
Path accountId
required
The owner account identifier. string (uuid)
Query groupIds
required
The identifiers. < string (uuid) > array(multi)

Responses

HTTP Code Description Schema
204 NoContent No Content

Field

Fields define the labels for customValues that are stored with the contacts

Name Schema
id
optional
integer (int32)
name
optional
string

Adds a field.

POST https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/fields

Parameters

Type Name Description Schema
Path accountId
required
The guid of the account. string (uuid)
Body field
required
The field. Field

Responses

HTTP Code Description Schema
201 Created Field

Gets a field by guid.

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/fields/{fieldId}

Parameters

Type Name Description Schema
Path accountId
required
The account guid. string (uuid)
Path fieldId
required
The field id. integer (int32)

Gets all fields for and account.

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/fields

Parameters

Type Name Description Schema
Path accountId
required
The accountId. string (uuid)

Updates a field.

PUT https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/fields/{fieldId}

Parameters

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

Responses

HTTP Code Description Schema
200 OK Field

Deletes a field.

DELETE https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/fields/{fieldId}

Parameters

Type Name Description Schema
Path accountId
required
The account identifier. string (uuid)
Path fieldId
required
The identifier. integer (int32)

Responses

HTTP Code Description Schema
204 NoContent No Content

OptOut

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.

OptOut Object

Name Schema
isActive
optional
boolean
type
optional
string
value
optional
string

Adds a OptOut tokens by type and value.

POST https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/optout/{tokenType}/{tokenValue}

Parameters

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

Responses

HTTP Code Description Schema
200 OK OptOut

Adds/Removes OptOut tokens in bulk.

POST https://api.cmtelecom.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).

Parameters

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

Responses

HTTP Code Description Schema
200 OK integer (int32)

Gets an OptOut token by type and value.

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/optout/{tokenType}/{tokenValue}

Parameters

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

Responses

HTTP Code Description Schema
200 OK OptOut

Gets all OptOut tokens for specified account.

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/optout

Parameters

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)

Responses

HTTP Code Description Schema
200 OK OptOut

Get OptOut tokens by type.

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/optout/{tokenType}

Parameters

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)

Responses

HTTP Code Description Schema
200 OK < OptOut > array

Gets the available OptOut token types for Organization

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/optout/types

Parameters

Type Name Description Schema
Path accountId
required
The account guid. string (uuid)

Responses

HTTP Code Description Schema
200 OK < ApiTokenType > array

ApiTokenType

Name Schema
amountOptIn
optional
integer (int32)
amountOptOut
optional
integer (int32)
description
optional
string
id
optional
string

Gets OptOut History for specified token type and value.

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/optout/{tokenType}/{tokenValue}/history

Parameters

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)

Responses

HTTP Code Description Schema
200 OK < OptOutHistory > array

OptOutHistory

Name Description Schema
createdBy
optional
Example : "00000000-0000-0000-0000-000000000000" string (uuid)
createdOnUtc
optional
string (date-time)
isActive
optional
boolean
message
optional
string

Search all Account OptOut tokens for specified value.

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/optout/search

Parameters

Type Name Description Schema
Path accountId
required
The account guid. string (uuid)
Query query
required
The query. string
Query skip
optional
The skip. integer (int32)
Query take
optional
The take. integer (int32)

Responses

HTTP Code Description Schema
200 OK OptOut

OptIn again by token type and value.

DELETE https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/optout/{tokenType}/{tokenValue}

Parameters

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

Responses

HTTP Code Description Schema
200 OK OptOut

Dump

Dump endpoints provides OptOut filtered list of contacts as a json array or CSV.

Dump OptOut filtered Contacts.

Contacts are filtered by OptOut lists first then only fields specified by the request are returned from the API.

Current available tokenTypes are sms or email.

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/dump/{tokenType}

Parameters

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.

Responses

HTTP Code Description Schema
200 OK Contact

Search

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

Search Contacts and Groups

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/search

Parameters

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)

Responses

HTTP Code Description Schema
200 OK Search

Search Groups

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/search/groups

Parameters

Type Name Description Schema
Path accountId
required
The account guid. string (uuid)
Query q
required
The query string. string

Responses

HTTP Code Description Schema
200 OK Search

Search Contacts in a Group

GET https://api.cmtelecom.com/addressbook/v2/accounts/{accountId}/groups/{groupId}/search

Parameters

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

Responses

HTTP Code Description Schema
200 OK Search