Business Messenger CDS API

1. Introduction

The Business Messenger Customer Data Storage (BM CDS) API is a standard REST HTTP API with JSON payload. It can be used to store customer subscription information, create messaging lists etc. The BM API authorization is implemented as the industry-standard OAuth 2.0 protocol. For more information, please refer to the OAuth2 Authentication Guidelines page.

API Call Examples

1. The following sample CURL call adds a new contact in your BM account:

curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer ACCESS_TOKEN" -d "{
    \"list_uuid\": \"LIST_UUID\",
    \"first_name\": \"John\",
    \"last_name\": \"Smith\",
    \"mobile\": \"+12025550100\",
    \"email\": \"john@example.com\",
    \"address\": \"St One\",
    \"zip\": \"9000\",
    \"city\": \"NY\",
    \"country\": \"US\"
  }" "https://api.horisen.pro/news/v1/services/SERVICE_UUID/cds/contacts"

2. An example call searching for contact(s) with +11111111111 mobile number:

curl --header "Accept: application/json" --header "Authorization: Bearer ACCESS_TOKEN" "https://api.horisen.pro/news/v1/services/SERVICE_UUID/cds/contacts?mobile=%2B11111111111"

3. If you need a batch import of contacts, an example of how to do that is given below:

curl -X POST "https://api.horisen.pro/news/v1/services/SERVICE_UUID/cds/imports?list_uuid=LIST_UUID&resolve_duplicate=update&identifier=mobile" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d @- << EOF
  [
    {"mobile":"+41765554366","first_name":"John","last_name":"Smith"},
    {"mobile":"+41765554783","first_name":"Mike","last_name":"Collins"},
    {"mobile":"+41775559513","first_name":"George","last_name":"Davis"}
  ]
  EOF

identifier=mobile defines that new and existing contacts will be mapped by the mobile property.
resolve_duplicate=update instructs what to do with duplicate records (in this case, updates the old record with the new data).

4. An example of how to filter results and make segmentation to see all contacts with e.g. first name John is given below:

curl 'https://api.horisen.pro/news/v1/services/SERVICE_UUID/cds/contacts?fields=lists,channels&page_number=1&page_size=10&query={"segmentation":[{"operator":"AND","rules":[{"field":"first_name","condition":"eq","value":"john","operator":"AND"}]}]}' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  --compressed

5. An example of how to filter results and make segmentation to see all contacts with specific birthday from one specific country is given below:

curl 'https://api.horisen.pro/news/v1/services/SERVICE_UUID/cds/contacts?fields=lists,channels&page_number=1&page_size=10&query={"segmentation":[{"operator":"AND","rules":[{"field":"country","condition":"eq","value":"CH","operator":"AND"},{"field":"birthday","condition":"eq","value":"1980-03-20","operator":"AND"}]}]}' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  --compressed

2. Methods Overview

2.1 Contact

Endpoints for Contacts Management.

GET/services/{serviceUuid}/cds/contacts
Returns a list of contacts.Read More
POST/services/{serviceUuid}/cds/contacts
Creates a new Contact.Read More
GET/services/{serviceUuid}/cds/contacts/{contactId}
Returns a Contact by UUID.Read More
PUT/services/{serviceUuid}/cds/contacts/{contactId}
Updates a Contact by UUID.Read More
PATCH/services/{serviceUuid}/cds/contacts/{contactId}
Patches a Contact by UUID.Read More
DELETE/services/{serviceUuid}/cds/contacts/{contactId}
Deletes a Contact by UUID.Read More
POST/services/{serviceUuid}/cds/imports
Imports contacts in a batch.Read More

2.2 List

Endpoints for Lists Management.

GET/services/{serviceUuid}/cds/lists
Returns an array of Lists.Read More
POST/services/{serviceUuid}/cds/lists
Creates a new List.Read More
GET/services/{serviceUuid}/cds/lists/{listId}
Returns a list by UUID.Read More
PUT/services/{serviceUuid}/cds/lists/{listId}
Updates a List.Read More
DELETE/services/{serviceUuid}/cds/lists/{listId}
Deletes a List.Read More

2.3 Field

Endpoints for Contact Fields Management.

GET/services/{serviceUuid}/cds/fields
Returns a list of Contact Fields.Read More
GET/services/{serviceUuid}/cds/custom_fields
Returns a list of Custom Fields.Read More
POST/services/{serviceUuid}/cds/custom_fields
Creates a Custom Field.Read More
GET/services/{serviceUuid}/cds/custom_fields/{customFieldsId}
Returns a Custom Field by ID.Read More
PUT/services/{serviceUuid}/cds/custom_fields/{customFieldsId}
Updates a Custom Field.Read More
DELETE/services/{serviceUuid}/cds/custom_fields/{customFieldsId}
Deletes a Custom Field.Read More

2.4 Segmentation

Endpoints for Segmentation Sets and Groups Management.

GET/services/{serviceUuid}/cds/segmentation_sets
Returns a list of Segmentation Sets.Read More
POST/services/{serviceUuid}/cds/segmentation_sets
Creates a new Segmentation Set.Read More
GET/services/{serviceUuid}/cds/segmentation_sets/{segmentationSetId}
Returns a Segmentation Set by UUID.Read More
PUT/services/{serviceUuid}/cds/segmentation_sets/{segmentationSetId}
Updates a Segmentation Set.Read More
DELETE/services/{serviceUuid}/cds/segmentation_sets/{segmentationSetId}
Deletes a Segmentation Set.Read More
GET/services/{serviceUuid}/cds/segmentation_groups
Returns a list of Segmentation Groups.Read More
POST/services/{serviceUuid}/cds/segmentation_groups
Creates a Segmentation Group.Read More
GET/services/{serviceUuid}/cds/segmentation_groups/{segmentationGroupId}
Returns a Segmentation Group by UUID.Read More
PUT/services/{serviceUuid}/cds/segmentation_groups/{segmentationGroupId}
Updates a Segmentation Group.Read More
DELETE/services/{serviceUuid}/cds/segmentation_groups/{segmentationGroupId}
Deletes a Segmentation Group Set.Read More

2.5 Subscription

Endpoints for Subscriptions and Options Management.

GET/services/{serviceUuid}/cds/subscriptions
Returns a list of Subscriptions.Read More
POST/services/{serviceUuid}/cds/subscriptions
Creates a new Subscription.Read More
GET/services/{serviceUuid}/cds/subscriptions/{subscriptionId}
Returns a Subscription by UUID.Read More
PUT/services/{serviceUuid}/cds/subscriptions/{subscriptionId}
Updates a Subscription.Read More
DELETE/services/{serviceUuid}/cds/subscriptions/{subscriptionId}
Deletes a Subscription.Read More
GET/services/{serviceUuid}/cds/subscriptions/options
Returns a list of Subscription Options.Read More
POST/services/{serviceUuid}/cds/subscriptions/options
Creates a Subscription Options.Read More
GET/services/{serviceUuid}/cds/subscriptions/options/{optionId}
Returns a Subscription Option by UUID.Read More
PUT/services/{serviceUuid}/cds/subscriptions/options/{optionId}
Updates a Subscription Option.Read More
DELETE/services/{serviceUuid}/cds/subscriptions/options/{optionId}
Deletes a Subscription Option.Read More
GET/services/{serviceUuid}/cds/subscriptions/members
Returns a list of a Subscription Option Members.Read More
POST/services/{serviceUuid}/cds/subscriptions/members
Creates or Updates a Subscription Member.Read More

2.6 Group

Endpoints for Groups Management.

GET/services/{serviceUuid}/cds/groups
Returns a list of Groups.Read More
POST/services/{serviceUuid}/cds/groups
Creates a new Group.Read More
GET/services/{serviceUuid}/cds/groups/{groupId}
Returns a Group by UUID.Read More
PUT/services/{serviceUuid}/cds/groups/{groupId}
Updates a Group.Read More
DELETE/services/{serviceUuid}/cds/groups/{groupId}
Deletes a Group.Read More
GET/services/{serviceUuid}/cds/group_lists
Returns a list of Group Lists.Read More
POST/services/{serviceUuid}/cds/group_lists
Creates a Group List.Read More
GET/services/{serviceUuid}/cds/group_lists/{groupListId}
Returns a Group List by UUID.Read More
PUT/services/{serviceUuid}/cds/group_lists/{groupListId}
Updates a Group List.Read More
GET/services/{serviceUuid}/cds/group_segmentation
Returns a list of Group Segmentations.Read More
POST/services/{serviceUuid}/cds/group_segmentation
Creates a new Group Segmentation.Read More
GET/services/{serviceUuid}/cds/group_segmentation/{groupSegmentationId}
Gets a Group Segmentation by UUID.Read More
PUT/services/{serviceUuid}/cds/group_segmentation/{groupSegmentationId}
Updates a Group Segmentation.Read More

2.7 Touchpoint

Endpoints for Touchpoints Management.

GET/services/{serviceUuid}/cds/touchpoints
Returns a list of Touchpoints.Read More
POST/services/{serviceUuid}/cds/touchpoints
Creates a new Touchpoint.Read More
GET/services/{serviceUuid}/cds/touchpoints/{touchpointId}
Returns a Touchpoint by UUID.Read More
PUT/services/{serviceUuid}/cds/touchpoints/{touchpointId}
Updates a Touchpoint.Read More
DELETE/services/{serviceUuid}/cds/touchpoints/{touchpointId}
Deletes a Touchpoint.Read More
GET/services/{serviceUuid}/cds/touchpoints/members
Returns a list of Touchpoint Members.Read More
POST/services/{serviceUuid}/cds/touchpoints/members
Creates or Updates a Touchpoint Membership.Read More

2.8 Interest

Endpoints for Interests Management.

GET/services/{serviceUuid}/cds/interests
Returns a list of Interests.Read More
POST/services/{serviceUuid}/cds/interests
Creates a new Interest.Read More
GET/services/{serviceUuid}/cds/interests/{interestId}
Gets an Interest by UUID.Read More
PUT/services/{serviceUuid}/cds/interests/{interestId}
Updates an Interest.Read More
DELETE/services/{serviceUuid}/cds/interests/{interestId}
Deletes an Interest.Read More
GET/services/{serviceUuid}/cds/interests/members
Returns a list of Interest Members.Read More
POST/services/{serviceUuid}/cds/interests/members
Creates or Updates an Interest Member.Read More

3. Methods Details

3.1 Contact

Endpoints for Contacts Management.

GET/services/{serviceUuid}/cds/contacts
Returns a list of contacts.Up

Method Overview

The method returns a list of contacts.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
fields array[string] (query) Optional fields.
Available values : lists, show_deleted, count_only, channels.
list_uuids array[string] (query) List UUIDs (comma-separated).
subscription_uuids array[string] (query) Subscription Options UUIDs (comma-separated).
interest_uuids array[string] (query) Interest UUIDs (comma-separated).
touchpoint_uuids array[string] (query) Touchpoint UUIDs (comma-separated).
member_status string (query) Member status. Available values : subscribed, unsubscribed.
subscription_status string (query) Subscription member status. Available values : subscribed, unsubscribed.
opt_status string (query) Opt status. Available values : in, out.
opt_status_webpush string (query) Opt status webpush. Available values : in, out.
gender string (query) Gender. Available values : male, female.
mobile string (query) Mobile (E.164 with + prefix).
email string (query) Email.
webpush_subscription string (query) Webpush subscription.
first_name string (query) First Name.
last_name string (query) Last Name.
age string (query) Age.
query string (query) Segmentation.
group_uuid string (query) Group UUID.
page_number integer (query) A page number. The default value: 1.
page_size integer (query) A page size. The default value: 10.
sort string (query) Sort order for the result records.
Available values: mobile, -mobile, first_name, -first_name, last_name, -last_name, created_dt, -created_dt, birthday, -birthday, gender, -gender, updated_dt, -updated_dt.
required array[string] (query) Returns contacts which have these fields defined: 'mobile', 'email', 'birthday', 'first_name', 'last_name'.
Available values: mobile, email, birthday, first_name, last_name.
updated_dt string (query) The date/time when the content was updated. It is in rfc3339 format. You can use operators for this field, e.g. gt(updated_dt)=2020-03-01T09:21:11+00:00 to get all contacts updated after the specified time.
channel_name string (query) Channel name.
Available values: telegram, viber, facebook, instagram.
channel_identifier string (query) Alias/Chat ID.
channel_opt_status string (query) Opt status.
Available values: in, out.
uuids array[string] (query) Search contacts by their UUIDs (comma-separated).

Responses

Code Description Links
200 List of Contacts. No links.
default Unexpected error. No links.

Success Response 200: List of Contacts

{
  "data": [
    {
      "uuid": "string",
      "created_dt": "string",
      "updated_dt": "string",
      "list_uuid": "string",
      "first_name": "string",
      "last_name": "string",
      "second_name": "string",
      "nick_name": "string",
      "gender": "string",
      "birthday": "string",
      "salutation": "string",
      "title": "string",
      "language": "string",
      "nationality": "string",
      "mobile": "string",
      "email": "string",
      "phone": "string",
      "address": "string",
      "zip": "string",
      "city": "string",
      "region": "string",
      "country": "string",
      "b_mobile": "string",
      "b_email": "string",
      "b_phone": "string",
      "b_address": "string",
      "b_zip": "string",
      "b_city": "string",
      "b_region": "string",
      "b_country": "string",
      "b_job_title": "string",
      "b_department": "string",
      "b_reception_code": "string",
      "channel_telegram_identifier": "string",
      "channel_telegram_opt_status": "in",
      "channel_telegram_data": {},
      "channels": [
        {
          "opt_status": "in",
          "channel_name": "string",
          "data": {},
          "identifier": "string"
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/contacts
Creates a new Contact.Up

Method Overview

The method creates a new Contact.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) Contact data.

Data Parameters

Contact data object example

{
  "list_uuid": "string",
  "first_name": "string",
  "last_name": "string",
  "second_name": "string",
  "nick_name": "string",
  "gender": "string",
  "birthday": "string",
  "salutation": "string",
  "title": "string",
  "language": "string",
  "nationality": "string",
  "mobile": "string",
  "email": "string",
  "phone": "string",
  "address": "string",
  "zip": "string",
  "city": "string",
  "region": "string",
  "country": "string",
  "b_mobile": "string",
  "b_email": "string",
  "b_phone": "string",
  "b_address": "string",
  "b_zip": "string",
  "b_city": "string",
  "b_region": "string",
  "b_country": "string",
  "b_job_title": "string",
  "b_department": "string",
  "b_reception_code": "string",
  "channel_telegram_identifier": "string",
  "channel_telegram_opt_status": "in",
  "channel_telegram_data": {}
}

Responses

Code Description Links
201 Created Contact. No links.
default Unexpected error. No links.

Success Response 201: Created Contact

{
  "uuid": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "list_uuid": "string",
  "first_name": "string",
  "last_name": "string",
  "second_name": "string",
  "nick_name": "string",
  "gender": "string",
  "birthday": "string",
  "salutation": "string",
  "title": "string",
  "language": "string",
  "nationality": "string",
  "mobile": "string",
  "email": "string",
  "phone": "string",
  "address": "string",
  "zip": "string",
  "city": "string",
  "region": "string",
  "country": "string",
  "b_mobile": "string",
  "b_email": "string",
  "b_phone": "string",
  "b_address": "string",
  "b_zip": "string",
  "b_city": "string",
  "b_region": "string",
  "b_country": "string",
  "b_job_title": "string",
  "b_department": "string",
  "b_reception_code": "string",
  "channel_telegram_identifier": "string",
  "channel_telegram_opt_status": "in",
  "channel_telegram_data": {},
  "channels": [
    {
      "opt_status": "in",
      "channel_name": "string",
      "data": {},
      "identifier": "string"
    }
  ]
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/contacts/{contactId}
Returns a Contact by UUID.Up

Method Overview

The method returns a Contact by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
contactId (required) string (path) ID of a Contact to get.
fields array[string] (query) Optional fields (lists).

Responses

Code Description Links
200 Contact data. No links.
default Unexpected error. No links.

Success Response 200: Contact Data

{
  "uuid": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "list_uuid": "string",
  "first_name": "string",
  "last_name": "string",
  "second_name": "string",
  "nick_name": "string",
  "gender": "string",
  "birthday": "string",
  "salutation": "string",
  "title": "string",
  "language": "string",
  "nationality": "string",
  "mobile": "string",
  "email": "string",
  "phone": "string",
  "address": "string",
  "zip": "string",
  "city": "string",
  "region": "string",
  "country": "string",
  "b_mobile": "string",
  "b_email": "string",
  "b_phone": "string",
  "b_address": "string",
  "b_zip": "string",
  "b_city": "string",
  "b_region": "string",
  "b_country": "string",
  "b_job_title": "string",
  "b_department": "string",
  "b_reception_code": "string",
  "channel_telegram_identifier": "string",
  "channel_telegram_opt_status": "in",
  "channel_telegram_data": {},
  "channels": [
    {
      "opt_status": "in",
      "channel_name": "string",
      "data": {},
      "identifier": "string"
    }
  ]
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
PUT/services/{serviceUuid}/cds/contacts/{contactId}
Updates a Contact by UUID.Up

Method Overview

The method updates a Contact by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
contactId (required) string (path) ID of a Contact to update.
body (required) (body) Contact data.

Data Parameters

Contact data object example

{
  "list_uuid": "string",
  "first_name": "string",
  "last_name": "string",
  "second_name": "string",
  "nick_name": "string",
  "gender": "string",
  "birthday": "string",
  "salutation": "string",
  "title": "string",
  "language": "string",
  "nationality": "string",
  "mobile": "string",
  "email": "string",
  "phone": "string",
  "address": "string",
  "zip": "string",
  "city": "string",
  "region": "string",
  "country": "string",
  "b_mobile": "string",
  "b_email": "string",
  "b_phone": "string",
  "b_address": "string",
  "b_zip": "string",
  "b_city": "string",
  "b_region": "string",
  "b_country": "string",
  "b_job_title": "string",
  "b_department": "string",
  "b_reception_code": "string",
  "channel_telegram_identifier": "string",
  "channel_telegram_opt_status": "in",
  "channel_telegram_data": {}
}

Responses

Code Description Links
200 Contact data. No links.
400 Invalid request. No links.
404 Resource not found. No links.
405 Validation exception. No links.
default Unexpected error. No links.

Success Response 200: Contact Data

{
  "uuid": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "list_uuid": "string",
  "first_name": "string",
  "last_name": "string",
  "second_name": "string",
  "nick_name": "string",
  "gender": "string",
  "birthday": "string",
  "salutation": "string",
  "title": "string",
  "language": "string",
  "nationality": "string",
  "mobile": "string",
  "email": "string",
  "phone": "string",
  "address": "string",
  "zip": "string",
  "city": "string",
  "region": "string",
  "country": "string",
  "b_mobile": "string",
  "b_email": "string",
  "b_phone": "string",
  "b_address": "string",
  "b_zip": "string",
  "b_city": "string",
  "b_region": "string",
  "b_country": "string",
  "b_job_title": "string",
  "b_department": "string",
  "b_reception_code": "string",
  "channel_telegram_identifier": "string",
  "channel_telegram_opt_status": "in",
  "channel_telegram_data": {},
  "channels": [
    {
      "opt_status": "in",
      "channel_name": "string",
      "data": {},
      "identifier": "string"
    }
  ]
}

Error Response 400: Invalid request

Error Response 404: Resource not found

Error Response 405: Validation exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
PATCH/services/{serviceUuid}/cds/contacts/{contactId}
Patches a Contact by UUID.Up

Method Overview

The method patches a Contact by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
contactId (required) string (path) ID of a Contact to update.
body (required) (body) Contact Status.

Data Parameters

Contact Status object example

{
  "opt_status": "in",
  "opt_status_webpush": "in",
  "channel_telegram_identifier": "string",
  "channel_telegram_opt_status": "in"
}

Responses

Code Description Links
200 Contact data. No links.
400 Invalid request. No links.
404 Resource not found. No links.
405 Validation exception. No links.
default Unexpected error. No links.

Success Response 200: Contact Data

{
  "uuid": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "list_uuid": "string",
  "first_name": "string",
  "last_name": "string",
  "second_name": "string",
  "nick_name": "string",
  "gender": "string",
  "birthday": "string",
  "salutation": "string",
  "title": "string",
  "language": "string",
  "nationality": "string",
  "mobile": "string",
  "email": "string",
  "phone": "string",
  "address": "string",
  "zip": "string",
  "city": "string",
  "region": "string",
  "country": "string",
  "b_mobile": "string",
  "b_email": "string",
  "b_phone": "string",
  "b_address": "string",
  "b_zip": "string",
  "b_city": "string",
  "b_region": "string",
  "b_country": "string",
  "b_job_title": "string",
  "b_department": "string",
  "b_reception_code": "string",
  "channel_telegram_identifier": "string",
  "channel_telegram_opt_status": "in",
  "channel_telegram_data": {},
  "channels": [
    {
      "opt_status": "in",
      "channel_name": "string",
      "data": {},
      "identifier": "string"
    }
  ]
}

Error Response 400: Invalid request

Error Response 404: Resource not found

Error Response 405: Validation exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
DELETE/services/{serviceUuid}/cds/contacts/{contactId}
Deletes a Contact by UUID.Up

Method Overview

The method deletes a Contact by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
contactId (required) string (path) ID of a Contact to delete.
gdpr (required) string (query) If full GDPR delete should be executed.
Available values: yes, no.
The default value: no.

Responses

Code Description Links
204 Contact deleted. No links.
default Unexpected error. No links.

Success Response 204: Contact Deleted

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/imports
Imports contacts in a batch.Up

Method Overview

The method imports contacts in a batch.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
list_uuid (required) string (query) UUID of a list in which contacts should be imported.
option_uuids array[string] (query) A comma separated string of subscription option UUIDs.
update_option_uuids array[string] (query) A comma separated string of subscription option UUIDs used for updating of existing contacts when resolve action is subscribe or unsubscribe.
touchpoint_uuids array[string] (query) A comma separated string of touchpoint UUIDs.
interest_uuids array[string] (query) A comma separated string of interest UUIDs.
resolve_duplicate (required) string (query) Defines an action how to resolve found duplicates.
Available values: update, skip, subscribe, unsubscribe, delete, optin, optout.
The default value: update.
identifier (required) string (query) This field is to be used as a unique identifier of imported contacts.
The default value: mobile.
unset_invalid_fields array[string] (query) A comma separated list of fields code names which can be unset (nulled) if the sent value is invalid.
insert_opt_channels array[string] (query) A list of channels to opt-in or opt-out from, when creating new contacts.
Available values: sms, whatsapp.
The default value: sms.
update_opt_channels array[string] (query) A list of channels to opt-in or opt-out from, when updating existing contacts.
Available values: sms, whatsapp.
The default value: sms.
body (required) array (body) Array of Contacts to add.

Data Parameters

Contacts Array body object example

[
  {
    "first_name": "string",
    "last_name": "string",
    "second_name": "string",
    "nick_name": "string",
    "gender": "string",
    "birthday": "string",
    "salutation": "string",
    "title": "string",
    "language": "string",
    "nationality": "string",
    "mobile": "string",
    "email": "string",
    "phone": "string",
    "address": "string",
    "zip": "string",
    "city": "string",
    "region": "string",
    "country": "string",
    "b_mobile": "string",
    "b_email": "string",
    "b_phone": "string",
    "b_address": "string",
    "b_zip": "string",
    "b_city": "string",
    "b_region": "string",
    "b_country": "string",
    "b_job_title": "string",
    "b_department": "string",
    "b_reception_code": "string"
  }
]

Responses

Code Description Links
200 Import result. No links.
default Unexpected error. No links.

Success Response 200: Import result

{
  "created": 0,
  "deleted": 0,
  "invalid": 0,
  "updated": 0,
  "skipped": 0,
  "subscribed": 0,
  "unsubscribed": 0,
  "optedin": 0,
  "optedout": 0,
  "errors": [
    {
      "contact": {
        "uuid": "string",
        "created_dt": "string",
        "updated_dt": "string",
        "list_uuid": "string",
        "first_name": "string",
        "last_name": "string",
        "second_name": "string",
        "nick_name": "string",
        "gender": "string",
        "birthday": "string",
        "salutation": "string",
        "title": "string",
        "language": "string",
        "nationality": "string",
        "mobile": "string",
        "email": "string",
        "phone": "string",
        "address": "string",
        "zip": "string",
        "city": "string",
        "region": "string",
        "country": "string",
        "b_mobile": "string",
        "b_email": "string",
        "b_phone": "string",
        "b_address": "string",
        "b_zip": "string",
        "b_city": "string",
        "b_region": "string",
        "b_country": "string",
        "b_job_title": "string",
        "b_department": "string",
        "b_reception_code": "string",
        "channel_telegram_identifier": "string",
        "channel_telegram_opt_status": "in",
        "channel_telegram_data": {},
        "channels": [
          {
            "opt_status": "in",
            "channel_name": "string",
            "data": {},
            "identifier": "string"
          }
        ]
      },
      "errors": [
        {
          "name": "string",
          "message": "string",
          "description": "string"
        }
      ]
    }
  ]
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.2 List

Endpoints for Lists Management.

GET/services/{serviceUuid}/cds/lists
Returns an array of Lists.Up

Method Overview

The method returns an array of Lists.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
fields array[string] (query) Optional fields (totals, status, show_deleted, contacts_count).

Responses

Code Description Links
200 Array of Lists. No links.
default Unexpected error. No links.

Success Response 200: Array of Lists

{
  "data": [
    {
      "uuid": "string",
      "name": "string",
      "list_status": "string",
      "created_dt": "string",
      "updated_dt": "string",
      "subscribed": 0,
      "unsubscribed": 0,
      "contacts_count": 0
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/lists
Creates a new List.Up

Method Overview

The method creates a new List.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) List to add.

Data Parameters

List body object example

{
  "uuid": "string",
  "name": "string",
  "list_status": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "subscribed": 0,
  "unsubscribed": 0,
  "contacts_count": 0
}

Responses

Code Description Links
201 New List response. No links.
default Unexpected error. No links.

Success Response 201: New List response

{
  "uuid": "string",
  "name": "string",
  "list_status": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "subscribed": 0,
  "unsubscribed": 0,
  "contacts_count": 0
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/lists/{listId}
Returns a List by UUID.Up

Method Overview

The method returns a List by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
listId (required) string (path) ID of a List to get.

Responses

Code Description Links
200 List Data. No links.
default Unexpected error. No links.

Success Response 200: List Data

{
  "uuid": "string",
  "name": "string",
  "list_status": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "subscribed": 0,
  "unsubscribed": 0,
  "contacts_count": 0
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
PUT/services/{serviceUuid}/cds/lists/{listId}
Updates a List.Up

Method Overview

The method updates a List.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
listId (required) string (path) ID of a List to update.
body (required) (body) List data.

Data Parameters

List data object example

{
  "uuid": "string",
  "name": "string",
  "list_status": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "subscribed": 0,
  "unsubscribed": 0,
  "contacts_count": 0
}

Responses

Code Description Links
200 Resource updated. No links.
400 Invalid request. No links.
404 Resource not found. No links.
405 Validation exception. No links.
default Unexpected error. No links.

Success Response 200: Resource updated

Error Response 400: Invalid request

Error Response 404: Resource not found

Error Response 405: Validation exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
DELETE/services/{serviceUuid}/cds/lists/{listId}
Deletes a List by UUID.Up

Method Overview

The method deletes a List by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
listId (required) string (path) ID of a List to delete.

Responses

Code Description Links
204 List deleted. No links.
default Unexpected error. No links.

Success Response 204: List Deleted

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.3 Field

Endpoints for Contact Fields Management.

GET/services/{serviceUuid}/cds/fields
Returns a list of Contact Fields.Up

Method Overview

The method returns a list of Contact Fields.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
include_all string (query) Appends custom fields and returns more detailed information about fields (use value 1 to set it).
The default value: 1.

Responses

Code Description Links
200 List of all fields (when include_all = 1), in the case of 0 or none, simple array of strings is returned. No links.
default Unexpected error. No links.

Success Response 200: List of all fields (when include_all = 1), in the case of 0 or none, simple array of strings is returned

[
  {
    "display_name": "string",
    "field_type": "string",
    "field_name": "string",
    "mandatory": "no",
    "order_num": 0,
    "config": {},
    "identifier": "no"
  }
]

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/custom_fields
Returns a list of Custom Fields.Up

Method Overview

The method returns a list of Custom Fields.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.

Responses

Code Description Links
200 List of Custom Fields. No links.
default Unexpected error. No links.

Success Response 200: List of Custom Fields

{
  "data": [
    {
      "display_name": "string",
      "field_type": "string",
      "field_name": "string",
      "mandatory": "no",
      "order_num": 0,
      "config": {},
      "identifier": "no"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/custom_fields
Creates a Custom Field.Up

Method Overview

The method creates a Custom Field.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) Field data.

Data Parameters

Field body object example

{
  "display_name": "string",
  "field_type": "string",
  "field_name": "string",
  "mandatory": "no",
  "order_num": 0,
  "config": {},
  "identifier": "no"
}

Responses

Code Description Links
201 New Custom Field response. No links.
default Unexpected error. No links.

Success Response 201: New Custom Field response

{
  "display_name": "string",
  "field_type": "string",
  "field_name": "string",
  "mandatory": "no",
  "order_num": 0,
  "config": {},
  "identifier": "no"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/custom_fields/{customFieldsId}
Returns a Custom Field by ID.Up

Method Overview

The method returns a Custom Field by ID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
customFieldId (required) string (path) ID of a Custom Field to get.

Responses

Code Description Links
200 Custom Field data. No links.
default Unexpected error. No links.

Success Response 200: Custom Field data

{
  "display_name": "string",
  "field_type": "string",
  "field_name": "string",
  "mandatory": "no",
  "order_num": 0,
  "config": {},
  "identifier": "no"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
PUT/services/{serviceUuid}/cds/custom_fields/{customFieldsId}
Updates a Custom Field.Up

Method Overview

The method updates a Custom Field.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
customFieldID (required) string (path) ID of a Custom Field to update.
body (required) (body) Custom Field data.

Data Parameters

Custom Field data object example

{
  "display_name": "string",
  "field_type": "string",
  "field_name": "string",
  "mandatory": "no",
  "order_num": 0,
  "config": {},
  "identifier": "no"
}

Responses

Code Description Links
200 Resource updated. No links.
400 Invalid request. No links.
404 Resource not found. No links.
405 Validation exception. No links.
default Unexpected error. No links.

Success Response 200: Resource updated

Error Response 400: Invalid request

Error Response 404: Resource not found

Error Response 405: Validation exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
DELETE/services/{serviceUuid}/cds/custom_fields/{customFieldsId}
Deletes a Custom Field by ID.Up

Method Overview

The method deletes a Custom Field by ID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
customFieldId (required) string (path) ID of a Custom Field to delete.

Responses

Code Description Links
204 Custom Field Deleted. No links.
default Unexpected error. No links.

Success Response 204: Custom Field Deleted

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.4 Segmentation

Endpoints for Segmentation Sets and Groups Management.

GET/services/{serviceUuid}/cds/segmentation_sets
Returns a list of Segmentation Sets.Up

Method Overview

The method returns a list of Segmentation Sets.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.

Responses

Code Description Links
200 List of Segmentation Sets. No links.
default Unexpected error. No links.

Success Response 200: List of Segmentation Sets

{
  "data": [
    {
      "uuid": "string",
      "name": "string",
      "data": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/segmentation_sets
Creates a new Segmentation Set.Up

Method Overview

The method creates a new Segmentation Set.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) Segmentation Set data.

Data Parameters

Segmentation Sets data object example

{
  "uuid": "string",
  "name": "string",
  "data": "string"
}

Responses

Code Description Links
201 New Segmentation Set response. No links.
default Unexpected error. No links.

Success Response 201: New Segmentation Set response

{
  "uuid": "string",
  "name": "string",
  "data": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/segmentation_sets/{segmentationSetId}
Returns a Segmentation Set by UUID.Up

Method Overview

The method returns a Segmentation Set by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
segmentationSetId (required) string (path) ID of a Segmentation Set to get.

Responses

Code Description Links
200 Segmentation Set Data. No links.
default Unexpected error. No links.

Success Response 200: Segmentation Set Data

{
  "uuid": "string",
  "name": "string",
  "data": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
PUT/services/{serviceUuid}/cds/segmentation_sets/{segmentationSetId}
Updates a Segmentation Set.Up

Method Overview

The method updates a Segmentation Set.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
segmentationSetId (required) string (path) ID of a Segmentation Set to update.
body (required) (body) Segmentation Set data.

Data Parameters

Segmentation Set data object example

{
  "uuid": "string",
  "name": "string",
  "data": "string"
}

Responses

Code Description Links
200 Resource updated. No links.
400 Invalid request. No links.
404 Resource not found. No links.
405 Validation exception. No links.
default Unexpected error. No links.

Success Response 200: Resource updated

Error Response 400: Invalid request

Error Response 404: Resource not found

Error Response 405: Validation exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
DELETE/services/{serviceUuid}/cds/segmentation_sets/{segmentationSetId}
Deletes a Segmentation Set.Up

Method Overview

The method deletes a Segmentation Set.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
segmentationSetId (required) string (path) ID of a Segmentation Set to delete.

Responses

Code Description Links
204 Segmentation Set deleted. No links.
default Unexpected error. No links.

Success Response 204: Segmentation Set deleted

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/segmentation_groups
Returns a list of Segmentation Groups.Up

Method Overview

The method returns a list of Segmentation Groups.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.

Responses

Code Description Links
200 List of Segmentation Groups. No links.
default Unexpected error. No links.

Success Response 200: List of Segmentation Groups

{
  "data": [
    {
      "uuid": "string",
      "name": "string",
      "data": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/segmentation_groups
Creates a Segmentation Group.Up

Method Overview

The method creates a Segmentation Group.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) Segmentation Group data.

Data Parameters

Segmentation Group body object example

{
  "uuid": "string",
  "name": "string",
  "data": "string"
}

Responses

Code Description Links
201 New Segmentation Group created. No links.
default Unexpected error. No links.

Success Response 201: New Segmentation Group Created

{
  "uuid": "string",
  "name": "string",
  "data": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/segmentation_groups/{segmentationGroupId}
Returns a Segmentation Group by UUID.Up

Method Overview

The method returns a Segmentation Group by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
segmentationGroupId (required) string (path) ID of a Segmentation Group to get.

Responses

Code Description Links
200 Segmentation Group data. No links.
default Unexpected error. No links.

Success Response 200: Segmentation Group data

{
  "uuid": "string",
  "name": "string",
  "data": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
PUT/services/{serviceUuid}/cds/segmentation_groups/{segmentationGroupId}
Updates a Segmentation Group.Up

Method Overview

The method updates a Segmentation Group.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
segmentationGroupId (required) string (path) ID of a Segmentation Group to update.
body (required) (body) Segmentation Group data.

Data Parameters

Segmentation Group object example

{
  "uuid": "string",
  "name": "string",
  "data": "string"
}

Responses

Code Description Links
200 Resource updated. No links.
400 Invalid request. No links.
404 Resource not found. No links.
405 Validation exception. No links.
default Unexpected error. No links.

Success Response 200: Resource updated

Error Response 400: Invalid request

Error Response 404: Resource not found

Error Response 405: Validation exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
DELETE/services/{serviceUuid}/cds/segmentation_groups/{segmentationGroupId}
Deletes a Segmentation Group Set.Up

Method Overview

The method deletes a Segmentation Group Set.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
segmentationGroupID (required) string (path) ID of a Segmentation Group to delete.

Responses

Code Description Links
204 Segmentation Group deleted. No links.
default Unexpected error. No links.

Success Response 204: Segmentation Group deleted

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.5 Subscription

Endpoints for Subscriptions and Options Management.

GET/services/{serviceUuid}/cds/subscriptions
Returns a list of Subscriptions.Up

Method Overview

The method returns a list of Subscriptions.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
fields array[string] (query) Optional fields (show_deleted).

Responses

Code Description Links
200 List of Subscriptions. No links.
default Unexpected error. No links.

Success Response 200: List of Subscriptions

{
  "data": [
    {
      "uuid": "string",
      "name": "string",
      "description": "string",
      "created_dt": "string",
      "updated_dt": "string",
      "status": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/subscriptions
Creates a new Subscription.Up

Method Overview

The method creates a new Subscription.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) Subscription data.

Data Parameters

Subscription body object example

{
  "uuid": "string",
  "name": "string",
  "description": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "status": "string"
}

Responses

Code Description Links
201 New Subscription created. No links.
default Unexpected error. No links.

Success Response 201: New Subscription Created

{
  "uuid": "string",
  "name": "string",
  "description": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "status": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/subscriptions/{subscriptionId}
Returns a Subscription by UUID.Up

Method Overview

The method returns a Subscription by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
subscriptionId (required) string (path) ID of a Subscription to get.

Responses

Code Description Links
200 Subscription Data Received. No links.
default Unexpected error. No links.

Success Response 200: Subscription Data Received

{
  "uuid": "string",
  "name": "string",
  "description": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "status": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
PUT/services/{serviceUuid}/cds/subscriptions/{subscriptionId}
Updates a Subscription.Up

Method Overview

The method updates a Subscription.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
subscriptionId (required) string (path) ID of a Subscription to update.
body (required) (body) Subscription Option data.

Data Parameters

Subscription option data object example

{
  "uuid": "string",
  "name": "string",
  "description": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "status": "string"
}

Responses

Code Description Links
200 Resource updated. No links.
400 Invalid request. No links.
404 Resource not found. No links.
405 Validation exception. No links.
default Unexpected error. No links.

Success Response 200: Resource updated

Error Response 400: Invalid request

Error Response 404: Resource not found

Error Response 405: Validation exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
DELETE/services/{serviceUuid}/cds/subscriptions/{subscriptionId}
Deletes a Subscription.Up

Method Overview

The method deletes a Subscription.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
subscriptionId (required) string (path) ID of a Subscription to delete.

Responses

Code Description Links
204 Subscription Option deleted. No links.
default Unexpected error. No links.

Success Response 204: Subscription Option deleted

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/subscriptions/options
Returns a list of Subscription Options.Up

Method Overview

The method returns a list of Subscription Options.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
subscription_uuid string (query) ID of a Subscription Option to get.
fields array[string] (query) Optional fields (totals, status, show_deleted)

Responses

Code Description Links
200 List of Subscription Option. No links.
default Unexpected error. No links.

Success Response 200: List of Subscription Option

{
  "data": [
    {
      "uuid": "string",
      "name": "string",
      "subscription_uuid": "string",
      "order_num": "string",
      "description": "string",
      "created_dt": "string",
      "updated_dt": "string",
      "status": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/subscriptions/options
Creates a Subscription Options.Up

Method Overview

The method creates a Subscription Options.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) A Subscription Option data.

Data Parameters

Subscription Option data example

{
  "uuid": "string",
  "name": "string",
  "subscription_uuid": "string",
  "order_num": "string",
  "description": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "status": "string"
}

Responses

Code Description Links
201 New Subscription Option response. No links.
default Unexpected error. No links.

Success Response 201: New Subscription Option response

{
  "uuid": "string",
  "name": "string",
  "subscription_uuid": "string",
  "order_num": "string",
  "description": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "status": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/subscriptions/options/{optionId}
Returns a Subscription Option by UUID.Up

Method Overview

The method returns a Subscription Option by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
optionId (required) string (path) ID of a Subscriptions Option to get.

Responses

Code Description Links
200 Subscriptions Option Data. No links.
default Unexpected error. No links.

Success Response 200: Subscriptions Option Data

{
  "uuid": "string",
  "name": "string",
  "subscription_uuid": "string",
  "order_num": "string",
  "description": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "status": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
PUT/services/{serviceUuid}/cds/subscriptions/options/{optionId}
Updates a Subscription Option.Up

Method Overview

The method updates a Subscription Option.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
optionId (required) string (path) ID of a Subscriptions Option to update.
body (required) (body) Subscription Option data.

Data Parameters

Subscription Option data example

{
  "uuid": "string",
  "name": "string",
  "subscription_uuid": "string",
  "order_num": "string",
  "description": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "status": "string"
}

Responses

Code Description Links
200 Resource updated. No links.
400 Invalid request. No links.
404 Resource not found. No links.
405 Validation exception. No links.
default Unexpected error. No links.

Success Response 200: Resource updated

Error Response 400: Invalid request

Error Response 404: Resource not found

Error Response 405: Validation exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
DELETE/services/{serviceUuid}/cds/subscriptions/options/{optionId}
Deletes a Subscription Option.Up

Method Overview

The method deletes a Subscription Option.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
optionId (required) string (path) ID of a Subscription Option to delete.

Responses

Code Description Links
204 Subscription Option deleted. No links.
default Unexpected error. No links.

Success Response 204: Subscription Option deleted

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/subscriptions/members
Returns a list of a Subscription Option Members.Up

Method Overview

The method returns a list of a Subscription Option Members.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
contact_uuid string (query) Filters memberships by UUID of a contact.
option_uuid string (query) Filters memberships by UUID of a subscription option.

Responses

Code Description Links
200 List of Subscription Members. No links.
default Unexpected error. No links.

Success Response 200: List of Subscription Members

{
  "data": [
    {
      "uuid": "string",
      "option_uuid": "string",
      "contact_uuid": "string",
      "status": "string",
      "joined_dt": "string",
      "updated_dt": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/subscriptions/members
Creates or Updates a Subscription Member.Up

Method Overview

The method creates or updates a Subscription Member.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) Subscription Member data to add.

Data Parameters

Subscription Member data body object example

{
  "option_uuid": "string",
  "contact_uuid": "string",
  "status": "subscribed"
}

Responses

Code Description Links
201 New Subscription Member added or updated. No links.
default Unexpected error. No links.

Success Response 201: New Subscription Member Added or Updated

{
  "uuid": "string",
  "option_uuid": "string",
  "contact_uuid": "string",
  "status": "string",
  "joined_dt": "string",
  "updated_dt": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.6 Group

Endpoints for Groups Management.

GET/services/{serviceUuid}/cds/groups
Returns a list of Groups.Up

Method Overview

The method returns a list of Groups.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
fields array[string] (query) Optional fields (total, status, show_deleted).

Responses

Code Description Links
200 List of Groups. No links.
default Unexpected error. No links.

Success Response 200: List of Groups

{
  "data": [
    {
      "uuid": "string",
      "name": "string",
      "group_status": "string",
      "type": "string",
      "match_type": "string",
      "list_uuids": "string",
      "segmentation_uuids": "string",
      "created_dt": "string",
      "updated_dt": "string",
      "description": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/groups
Creates a new Group.Up

Method Overview

The method creates a new Group.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) Group data to add.

Data Parameters

Group body object example

{
  "uuid": "string",
  "name": "string",
  "group_status": "string",
  "type": "string",
  "match_type": "string",
  "list_uuids": "string",
  "segmentation_uuids": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "description": "string"
}

Responses

Code Description Links
201 New Group created. No links.
default Unexpected error. No links.

Success Response 201: New Group Created

{
  "uuid": "string",
  "name": "string",
  "group_status": "string",
  "type": "string",
  "match_type": "string",
  "list_uuids": "string",
  "segmentation_uuids": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "description": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/groups/{groupId}
Returns a Group by UUID.Up

Method Overview

The method returns a Group by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
groupId (required) string (path) ID of a Group to get.

Responses

Code Description Links
200 Group Data Received. No links.
default Unexpected error. No links.

Success Response 200: Group Data Received

{
  "uuid": "string",
  "name": "string",
  "group_status": "string",
  "type": "string",
  "match_type": "string",
  "list_uuids": "string",
  "segmentation_uuids": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "description": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
PUT/services/{serviceUuid}/cds/groups/{groupId}
Updates a Group.Up

Method Overview

The method updates a Group.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
groupId (required) string (path) ID of a Group to update.
body (required) (body) Group data.

Data Parameters

Group body object example

{
  "uuid": "string",
  "name": "string",
  "group_status": "string",
  "type": "string",
  "match_type": "string",
  "list_uuids": "string",
  "segmentation_uuids": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "description": "string"
}

Responses

Code Description Links
200 Resource updated. No links.
400 Invalid request. No links.
404 Resource not found. No links.
405 Validation exception. No links.
default Unexpected error. No links.

Success Response 200: Resource updated

Error Response 400: Invalid request

Error Response 404: Resource not found

Error Response 405: Validation exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
DELETE/services/{serviceUuid}/cds/groups/{groupId}
Deletes a Group.Up

Method Overview

The method deletes a Group.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
groupId (required) string (path) ID of a Group to delete.

Responses

Code Description Links
204 Group deleted. No links.
default Unexpected error. No links.

Success Response 204: Group deleted

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/group_lists
Returns a list of Group Lists.Up

Method Overview

The method returns a list of Group Lists.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
list_uuid string (query) ID of a List to get.
group_uuid string (query) ID of a Group List to get.

Responses

Code Description Links
200 List of Group Lists. No links.
default Unexpected error. No links.

Success Response 200: List of Group Lists

{
  "data": [
    {
      "group_uuid": "string",
      "list_uuid": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/group_lists
Creates a Group List.Up

Method Overview

The method creates a Group List.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) A Group List data to add.

Data Parameters

Group List body object example

{
  "group_uuid": "string",
  "list_uuid": "string"
}

Responses

Code Description Links
201 New Group List response. No links.
default Unexpected error. No links.

Success Response 201: New Group List response

{
  "group_uuid": "string",
  "list_uuid": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/group_lists/{groupListId}
Returns a Group List by UUID.Up

Method Overview

The method returns a Group List by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
groupListId (required) string (path) ID of a Group List to get.

Responses

Code Description Links
200 Group List data. No links.
default Unexpected error. No links.

Success Response 200: Group List data

{
  "group_uuid": "string",
  "list_uuid": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
PUT/services/{serviceUuid}/cds/group_lists/{groupListId}
Updates a Group List.Up

Method Overview

The method updates a Group List.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
groupListId (required) string (path) ID of a Group List to update.
body (required) (body) A Group List data.

Data Parameters

Group List body object example

{
  "group_uuid": "string",
  "list_uuid": "string"
}

Responses

Code Description Links
200 Resource updated. No links.
400 Invalid request. No links.
404 Resource not found. No links.
405 Validation exception. No links.
default Unexpected error. No links.

Success Response 200: Resource updated

Error Response 400: Invalid request

Error Response 404: Resource not found

Error Response 405: Validation exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/group_segmentation
Returns a list of Group Segmentations.Up

Method Overview

The method returns a list of Group Segmentations.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
segmentation_uuid string (query) ID of a Segmentation to get.
group_uuid string (query) The ID of a Group Segmentation to get.

Responses

Code Description Links
200 List of Group Segmentation. No links.
default Unexpected error. No links.

Success Response 200: List of Group Segmentation

{
  "data": [
    {
      "group_uuid": "string",
      "segmentation_uuid": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/group_segmentation
Creates a new Group Segmentation.Up

Method Overview

The method creates a new Group Segmentation.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) A Group Segmentation data to add.

Data Parameters

Group Segmentation body object example

{
  "group_uuid": "string",
  "segmentation_uuid": "string"
}

Responses

Code Description Links
201 New Group Segmentation response. No links.
default Unexpected error. No links.

Success Response 201: New Group Segmentation response

{
  "group_uuid": "string",
  "segmentation_uuid": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/group_segmentation/{groupSegmentationId}
Gets a Group Segmentation by UUID.Up

Method Overview

The method gets a Group Segmentation by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
groupSegmentationId (required) string (path) ID of a Group Segmentation to get.

Responses

Code Description Links
200 Group Segmentation data. No links.
default Unexpected error. No links.

Success Response 200: Group Segmentation data

{
  "group_uuid": "string",
  "segmentation_uuid": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
PUT/services/{serviceUuid}/cds/group_segmentation/{groupSegmentationId}
Updates a Group Segmentation.Up

Method Overview

The method updates a Group Segmentation.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
groupSegmentationId (required) string (path) ID of a Group Segmentation to update.
body (required) (body) Group Segmentation data.

Data Parameters

Group Segmentation body object example

{
  "group_uuid": "string",
  "segmentation_uuid": "string"
}

Responses

Code Description Links
200 Resource updated. No links.
400 Invalid request. No links.
404 Resource not found. No links.
405 Validation exception. No links.
default Unexpected error. No links.

Success Response 200: Resource updated

Error Response 400: Invalid request

Error Response 404: Resource not found

Error Response 405: Validation exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.7 Touchpoint

Endpoints for Touchpoints Management.

GET/services/{serviceUuid}/cds/touchpoints
Returns a list of Touchpoints.Up

Method Overview

The method returns a list of Touchpoints.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
contact_uuid string (path) ID of a Contact to get.
fields array[string] (query) Optional fields (show_deleted).

Responses

Code Description Links
200 List of Touchpoints. No links.
default Unexpected error. No links.

Success Response 200: List of Touchpoints

{
  "data": [
    {
      "uuid": "string",
      "name": "string",
      "status": "string",
      "type": "string",
      "default_date": "string",
      "created_dt": "string",
      "updated_dt": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/touchpoints
Creates a new Touchpoint.Up

Method Overview

The method creates a new Touchpoint.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) A Touchpoint data to add.

Data Parameters

Touchpoint data object example

{
  "uuid": "string",
  "name": "string",
  "status": "string",
  "type": "string",
  "default_date": "string",
  "created_dt": "string",
  "updated_dt": "string"
}

Responses

Code Description Links
201 New Touchpoint created. No links.
default Unexpected error. No links.

Success Response 201: New Touchpoint Created

{
  "uuid": "string",
  "name": "string",
  "status": "string",
  "type": "string",
  "default_date": "string",
  "created_dt": "string",
  "updated_dt": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/touchpoints/{touchpointId}
Gets a Touchpoint by UUID.Up

Method Overview

The method gets a Touchpoint by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
touchpointId (required) string (path) ID of a Touchpoint to get.

Responses

Code Description Links
200 Touchpoint data. No links.
default Unexpected error. No links.

Success Response 200: Touchpoint Data

{
  "uuid": "string",
  "name": "string",
  "status": "string",
  "type": "string",
  "default_date": "string",
  "created_dt": "string",
  "updated_dt": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
PUT/services/{serviceUuid}/cds/touchpoints/{touchpointId}
Updates a Touchpoint.Up

Method Overview

The method updates a Touchpoint.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
touchpointId (required) string (path) ID of a Touchpoint to get.
body (required) (body) A Touchpoint data.

Data Parameters

Touchpoint data object example

{
  "uuid": "string",
  "name": "string",
  "status": "string",
  "type": "string",
  "default_date": "string",
  "created_dt": "string",
  "updated_dt": "string"
}

Responses

Code Description Links
200 Resource updated. No links.
400 Invalid request. No links.
404 Resource not found. No links.
405 Validation exception. No links.
default Unexpected error. No links.

Success Response 200: Resource updated

Error Response 400: Invalid request

Error Response 404: Resource not found

Error Response 405: Validation exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
DELETE/services/{serviceUuid}/cds/touchpoints/{touchpointId}
Deletes a Touchpoint.Up

Method Overview

The method deletes a Touchpoint.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
touchpointId (required) string (path) ID of a Touchpoint to delete.

Responses

Code Description Links
204 Touchpoint deleted. No links.
default Unexpected error. No links.

Success Response 204: Touchpoint deleted

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/touchpoints/members
Returns a list of Touchpoint Members.Up

Method Overview

The method returns a list of Touchpoint Members.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
contact_uuid string (query) Filters memberships by UUID of a Contact.
touchpoint_uuid string (query) Filters memberships by UUID of a Touchpoint.

Responses

Code Description Links
200 List of Touchpoint Members. No links.
default Unexpected error. No links.

Success Response 200: List of Touchpoint Members

{
  "data": [
    {
      "uuid": "string",
      "status": "string",
      "touchpoint_uuid": "string",
      "contact_uuid": "string",
      "joined_dt": "string",
      "updated_dt": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/touchpoints/members
Creates or Updates a Touchpoint Membership.Up

Method Overview

The method creates or updates a Touchpoint Membership.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) A Touchpoint Member data to add.

Data Parameters

Touchpoint Member object example

{
  "status": "subscribed",
  "touchpoint_uuid": "string",
  "contact_uuid": "string"
}

Responses

Code Description Links
201 New Touchpoint Member response. No links.
default Unexpected error. No links.

Success Response 201: New Touchpoint Member Response

{
  "uuid": "string",
  "status": "string",
  "touchpoint_uuid": "string",
  "contact_uuid": "string",
  "joined_dt": "string",
  "updated_dt": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

3.8 Interest

Endpoints for Interests management.

GET/services/{serviceUuid}/cds/interests
Returns a list of Interests.Up

Method Overview

The method returns a list of Interests.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
fields array[string] (query) Optional fields (status, parent_id, level).
embed array[string] (query) Embeds additional entities.

Responses

Code Description Links
200 List of Interests. No links.
default Unexpected error. No links.

Success Response 200: List of Interests

{
  "data": [
    {
      "uuid": "string",
      "parent_id": 0,
      "service_id": 0,
      "name": "string",
      "status": "string",
      "created_dt": "string",
      "updated_dt": "string",
      "level": 0,
      "description": "string",
      "order_num": 0
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/interests
Creates a new Interest.Up

Method Overview

The method creates a new Interest.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) Interest data.

Data Parameters

Interest data object example

{
  "uuid": "string",
  "parent_id": 0,
  "service_id": 0,
  "name": "string",
  "status": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "level": 0,
  "description": "string",
  "order_num": 0
}

Responses

Code Description Links
201 New Interest created. No links.
default Unexpected error. No links.

Success Response 201: New Interest Created

{
  "uuid": "string",
  "parent_id": 0,
  "service_id": 0,
  "name": "string",
  "status": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "level": 0,
  "description": "string",
  "order_num": 0
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/interests/{interestId}
Gets an Interest by UUID.Up

Method Overview

The method gets an Interest by UUID.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
interestId (required) string (path) Interest ID to get.
embed array[string] (query) Embeds additional entities.

Responses

Code Description Links
200 Interest Data. No links.
default Unexpected error. No links.

Success Response 200: Interest Data

{
  "uuid": "string",
  "parent_id": 0,
  "service_id": 0,
  "name": "string",
  "status": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "level": 0,
  "description": "string",
  "order_num": 0
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
PUT/services/{serviceUuid}/cds/interests/{interestId}
Updates an Interest.Up

Method Overview

The method updates an Interest.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
interestId (required) string (path) ID of an Interest to get.
body (required) (body) Interest data.

Data Parameters

Interest data object example

{
  "uuid": "string",
  "parent_id": 0,
  "service_id": 0,
  "name": "string",
  "status": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "level": 0,
  "description": "string",
  "order_num": 0
}

Responses

Code Description Links
200 Resource updated. No links.
400 Invalid request. No links.
404 Resource not found. No links.
405 Validation exception. No links.
default Unexpected error. No links.

Success Response 200: Resource updated

Error Response 400: Invalid request

Error Response 404: Resource not found

Error Response 405: Validation exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
DELETE/services/{serviceUuid}/cds/interests/{interestId}
Deletes an Interest.Up

Method Overview

The method deletes an Interest.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
interestId (required) string (path) ID of an Interest to delete.

Responses

Code Description Links
204 Interest deleted. No links.
default Unexpected error. No links.

Success Response 204: Interest deleted

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
GET/services/{serviceUuid}/cds/interests/members
Returns a list of Interest Members.Up

Method Overview

The method returns a list of Interest Members.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
contact_uuid string (query) Filters memberships by UUID of a Contact.
interest_uuid string (query) Filters memberships by UUID of an Interest.

Responses

Code Description Links
200 List of Interests Members. No links.
default Unexpected error. No links.

Success Response 200: List of Interests Members

{
  "data": [
    {
      "uuid": "string",
      "status": "string",
      "interest_uuid": "string",
      "contact_uuid": "string"
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}
POST/services/{serviceUuid}/cds/interests/members
Creates or Updates an Interest Member.Up

Method Overview

The method creates or updates an Interest Member.

URL Parameters

Name Type Description
serviceUuid (required) string (path) BM account UUID.
body (required) (body) An Interest Member to create or update.

Data Parameters

Interest Member data object example

{
  "status": "subscribed",
  "interest_uuid": "string",
  "contact_uuid": "string"
}

Responses

Code Description Links
201 New Interest Member response. No links.
default Unexpected error. No links.

Success Response 201: New Interest Member response

{
  "uuid": "string",
  "status": "string",
  "interest_uuid": "string",
  "contact_uuid": "string"
}

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

4. Data Models

Data Models define the structure of a JSON document.

4.1 Data

Data describe all the data related to the Business Messenger CDS API.

ServiceCollection object properties:

Name Type Description
data (required) array An array of Service objects.
meta (required) object CollectionMeta object.

Service object properties:

Name Type Description
uuid (required) string BM account UUID.
status (required) string BM account status.
name (required) string BM account name.
partner_id (required) integer Partner ID.
start_dt (required) string BM account start date and time.
end_dt (required) string BM account end date and time.
created_dt string BM account date and time of creation.

ListsCollection object properties:

Name Type Description
data (required) array An array of List objects.
meta (required) object CollectionMeta object.

List object properties:

Name Type Description
uuid string List UUID.
name (required) string List name.
list_status string List status.
created_dt string List creation date and time.
updated_dt string List update date and time.
subscribed integer Number of subscribed contacts.
unsubscribed integer Number of unsubscribed contacts.
contact_count integer Total number of contacts.

JSON example

{
  "uuid": "string",
  "name": "string",
  "list_status": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "subscribed": 0,
  "unsubscribed": 0,
  "contacts_count": 0
}

GroupCollection object properties:

Name Type Description
data (required) array An array of Group objects.
meta (required) object CollectionMeta object.

Group object properties:

Name Type Description
uuid string Group UUID.
name (required) string Group name.
group_status string Group status.
type string Group type.
match_type string Match type.
list_uuids string Lists' UUIDs added to a group.
segmentation_uuids string Segmentation UUIDs.
created_dt string Group creation date and time.
updated_dt string Group update date and time.
description string Description of a group.

GroupListCollection object properties:

Name Type Description
data (required) array An array of GroupList objects.
meta (required) object CollectionMeta object.

GroupList object properties:

Name Type Description
group_uuid (required) string Group UUID.
list_uuid (required) string List UUID.

GroupSegmentationCollection object properties:

Name Type Description
data (required) array An array of GroupSegmentation objects.
meta (required) object CollectionMeta object.

GroupSegmentation object properties:

Name Type Description
group_uuid (required) string Group UUID.
segmentation_uuid (required) string Segmentation UUID.

SubscriptionCollection object properties:

Name Type Description
data (required) array An array of Subscription objects.
meta (required) object CollectionMeta object.

Subscription object properties:

Name Type Description
uuid string Subscription UUID.
name (required) string Subscription name.
description string Description of a subscription.
created_dt string Subscription creation date and time.
updated_dt string Subscription update date and time.
status string Subscription status.

JSON example

{
  "uuid": "string",
  "name": "string",
  "description": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "status": "string"
}

TouchpointCollection object properties:

Name Type Description
data (required) array An array of Touchpoint objects.
meta (required) object CollectionMeta object.

Touchpoint object properties:

Name Type Description
uuid string Touchpoint UUID.
name (required) string Touchpoint name.
status string Touchpoint status.
type string Touchpoint type.
default_dt string Touchpoint default date.
created_dt string Touchpoint creation date and time.
updated_dt string Touchpoint update date and time.

TouchpointMemberCreateCollection object properties:

Name Type Description
data (required) array An array of TouchpointMemberCreate objects.
meta (required) object CollectionMeta object.

TouchpointMemberCreate object properties:

Name Type Description
status (required) string Status of a contact. Possible values: subscribed, unsubscribed.
touchpoint_uuid (required) string Touchpoint UUID.
contact_uuid (required) string Contact UUID.

TouchpointMembersCollection object properties:

Name Type Description
data (required) array An array of TouchpointMember objects.
meta (required) object CollectionMeta object.

TouchpointMember object properties:

Name Type Description
uuid string Touchpoint member UUID.
status (required) string Touchpoint member status.
touchpoint_uuid (required) string Touchpoint UUID.
contact_uuid (required) string Member - contact UUID.
joined_dt string Date and time when contact joined.
updated_dt string Member updated date and time.

JSON example

{
  "uuid": "string",
  "status": "string",
  "touchpoint_uuid": "string",
  "contact_uuid": "string",
  "joined_dt": "string",
  "updated_dt": "string"
}

SubscriptionOptionCollection object properties:

Name Type Description
data (required) array An array of SubscriptionOption objects.
meta (required) object CollectionMeta object.

SubscriptionOption object properties:

Name Type Description
uuid string Subscription option UUID.
name (required) string Subscription option name.
subscription_uuid (required) string Subscription UUID.
order_num string Subscription option order number.
description string Subscription option description.
created_dt string Subscription option creation date and time.
updated_dt string Subscription option update date and time.
status string Subscription option status.

JSON example

{
  "uuid": "string",
  "name": "string",
  "subscription_uuid": "string",
  "order_num": "string",
  "description": "string",
  "created_dt": "string",
  "updated_dt": "string",
  "status": "string"
}

SubscriptionMemberCreate object properties:

Name Type Description
option_uuid (required) string Subscription option UUID.
contact_uuid (required) string Contact UUID.
status (required) string Subscription member status. Possible values: subscribed, unsubscribed.

SubscriptionMembersCollection object properties:

Name Type Description
data (required) array An array of SubscriptionMember objects.
meta (required) object CollectionMeta object.

SubscriptionMember object properties:

Name Type Description
uuid string Subscription member UUID.
option_uuid (required) string Subscription option UUID.
contact_uuid (required) string Member - contact UUID.
status (required) string Subscription member status.
joined_dt string Subscription member date and time of joining.
updated_dt string Subscription member update date and time.

Channel object properties:

Name Type Description
opt_status string Opt status. Possible values: in, out.
channel_name string Channel name.
data object Channel data.
identifier string Channel identifier.

JSON example

{
  "opt_status": "in",
  "channel_name": "string",
  "data": {},
  "identifier": "string"
}

Contact object properties:

Name Type Description
uuid string Contact UUID.
created_dt string Contact creation date and time.
updated_dt string Contact update date and time.
list_uuid string List UUID a contact belongs to.
first_name string Contact's first name.
last_name string Contact's last name.
second_name string Contact's second name.
nick_name string Contact's nick name.
gender string Gender of a contact.
birthday string Birthday of a contact.
salutation string Salutation.
title string Title.
language string Language.
nationality string Nationality.
mobile string Mobile number.
email string Email.
phone string Phone number.
address string Address.
zip string Postal code.
city string City.
region string Region.
country string Country.
b_mobile string Business mobile number.
b_email string Business email.
b_phone string Business phone number.
b_address string Business address.
b_zip string Business address postal code.
b_city string Business address city.
b_region string Business address region.
b_country string Business address country.
b_job_title string Job title.
b_department string Department.
b_reception_code string Reception code.
channel_telegram_identifier string Channel telegram identifier.
channel_telegram_opt_status string Telegram channel status. Possible values: in, out.
channel_telegram_data object Channel telegram data.
channels array An array of Channel objects.

ContactCreate object properties:

Name Type Description
list_uuid (required) string List UUID.
first_name string Contact's first name.
last_name string Contact's last name.
second_name string Contact's second name.
nick_name string Contact's nick name.
gender string Gender of a contact.
birthday string Birthday of a contact.
salutation string Salutation.
title string Title.
language string Language.
nationality string Nationality.
mobile (required) string Mobile number.
email string Email.
phone string Phone number.
address string Address.
zip string Postal code.
city string City.
region string Region.
country string Country.
b_mobile string Business mobile number.
b_email string Business email.
b_phone string Business phone number.
b_address string Business address.
b_zip string Business address postal code.
b_city string Business address city.
b_region string Business address region.
b_country string Business address country.
b_job_title string Job title.
b_department string Department.
b_reception_code string Reception code.
channel_telegram_identifier string Channel telegram identifier.
channel_telegram_opt_status string Telegram channel status. Possible values: in, out.
channel_telegram_data object Channel telegram data.

ContactImport object properties:

Name Type Description
list_uuid (required) string List UUID.
first_name string Contact's first name.
last_name string Contact's last name.
second_name string Contact's second name.
nick_name string Contact's nick name.
gender string Gender of a contact.
birthday string Birthday of a contact.
salutation string Salutation.
title string Title.
language string Language.
nationality string Nationality.
mobile (required) string Mobile number.
email string Email.
phone string Phone number.
address string Address.
zip string Postal code.
city string City.
region string Region.
country string Country.
b_mobile string Business mobile number.
b_email string Business email.
b_phone string Business phone number.
b_address string Business address.
b_zip string Business address postal code.
b_city string Business address city.
b_region string Business address region.
b_country string Business address country.
b_job_title string Job title.
b_department string Department.
b_reception_code string Reception code.

ContactOptStatus object properties:

Name Type Description
opt_status (required) string Contact's opt status. Possible values: in, out.
opt_status_webpush string Contact's webpush opt status. Possible values: in, out.
channel_telegram_identifier string Channel telegram identifier.
channel_telegram_opt_status string Contact's telegram opt status. Possible values: in, out.

ContactsCollection object properties:

Name Type Description
data (required) array An array of Contact objects.
meta (required) object CollectionMeta object.

ContactCreateCollection object properties:

Name Type Description
data (required) array An array of ContactCreate objects.
meta (required) object CollectionMeta object.

ImportResponse object properties:

Name Type Description
created integer Number of created contacts after an import.
deleted integer Number of deleted contacts after an import.
invalid integer Number of invalid contacts after an import.
updated integer Number of updated contacts after an import.
skipped integer Number of skipped contacts after an import.
subscribed integer Number of subscribed contacts after an import.
unsubscribed integer Number of unsubscribed contacts after an import.
optedin integer Number of optedin contacts after an import.
optedout integer Number of optedout contacts after an import.
errors array An array of ImportErrorRecord objects.

ImportErrorRecord object properties:

Name Type Description
contact object Contact object
errors array An array of ErrorItem objects.

JSON example

{
  "created": 0,
  "deleted": 0,
  "invalid": 0,
  "updated": 0,
  "skipped": 0,
  "subscribed": 0,
  "unsubscribed": 0,
  "optedin": 0,
  "optedout": 0,
  "errors": [
    {
      "contact": {
        "uuid": "string",
        "created_dt": "string",
        "updated_dt": "string",
        "list_uuid": "string",
        "first_name": "string",
        "last_name": "string",
        "second_name": "string",
        "nick_name": "string",
        "gender": "string",
        "birthday": "string",
        "salutation": "string",
        "title": "string",
        "language": "string",
        "nationality": "string",
        "mobile": "string",
        "email": "string",
        "phone": "string",
        "address": "string",
        "zip": "string",
        "city": "string",
        "region": "string",
        "country": "string",
        "b_mobile": "string",
        "b_email": "string",
        "b_phone": "string",
        "b_address": "string",
        "b_zip": "string",
        "b_city": "string",
        "b_region": "string",
        "b_country": "string",
        "b_job_title": "string",
        "b_department": "string",
        "b_reception_code": "string",
        "channel_telegram_identifier": "string",
        "channel_telegram_opt_status": "in",
        "channel_telegram_data": {},
        "channels": [
          {
            "opt_status": "in",
            "channel_name": "string",
            "data": {},
            "identifier": "string"
          }
        ]
      },
      "errors": [
        {
          "name": "string",
          "message": "string",
          "description": "string"
        }
      ]
    }
  ]
}

CustomFieldsCollection object properties:

Name Type Description
data (required) array An array of CustomField objects.
meta (required) object CollectionMeta object.

CustomField object properties:

Name Type Description
display_name (required) string Displayed name of a custom field.
field_type (required) string Custom field type.
field_name string Custom field name.
mandatory (required) string If custom field is mandatory. Possible values: no, yes.
order_num (required) integer Field order number.
config object Custom field config data.
identifier (required) string Possible values: no, yes.

SegmentationGroupCollection object properties:

Name Type Description
data (required) array An array of SegmentationGroup objects.
meta (required) object CollectionMeta object.

SegmentationGroup object properties:

Name Type Description
uuid string Segmentation group UUID.
name (required) string Segmentation group name.
data (required) string Segmentation group data.

SegmentationSetCollection object properties:

Name Type Description
data (required) array An array of SegmentationSet objects.
meta (required) object CollectionMeta object.

SegmentationSet object properties:

Name Type Description
uuid string Segmentation set UUID.
name (required) string Segmentation set name.
data (required) string Segmentation name data.

InterestsCollection object properties:

Name Type Description
data (required) array An array of Interest objects.
meta (required) object CollectionMeta object.

Interest object properties:

Name Type Description
uuid string Interest UUID.
parent_id integer Parent ID.
service_id integer BM account ID.
name (required) string Interest name.
status string Interest status.
created_dt string Interest date and time of creation.
updated_dt string Interest update date and time.
level integer Level of interest.
description string Description of an interest.
order_num (required) integer Interest order number.

InterestMemberCreate object properties:

Name Type Description
status string Interest member status. Possible values: subscribed, unsubscribed.
interest_uuid string Interest UUID.
contact_uuid string Contact UUID.

InterestMember object properties:

Name Type Description
uuid string Interest member UUID.
status (required) string Interest member status.
interest_uuid (required) string Interest UUID.
contact_uuid (required) string Contact UUID.

JSON example

{
  "uuid": "string",
  "status": "string",
  "interest_uuid": "string",
  "contact_uuid": "string"
}

InterestMembersCollection object properties:

Name Type Description
data (required) array An array of InterestMember objects.
meta (required) object CollectionMeta object.

Error object properties:

Name Type Description
code (required) string Error code.
message (required) string Error message.
description string Description.
items array An array of ErrorItem objects.

ErrorItem object properties:

Name Type Description
name (required) string Error item name.
message (required) string Error item message.
description string Description.

JSON Example

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

4.2 Meta

Meta contains data for the number of rows and pages that have been received for a given API call.

CollectionMeta object properties:

Name Type Description
pagination (required) object CollectionMetaPagination object.

CollectionMetaPagination object properties:

Name Type Description
total (required) integer Total number of rows.
count (required) integer A number of rows in the current page.
perPage (required) integer The maximum rows per page.
currentPage (required) integer The current page number.
totalPages (required) integer Total number of pages.
links (required) object CollectionMetaPaginationLinks object.

CollectionMetaPaginationLinks object properties:

Name Type Description
first string Link to the first page.
last string Link to the last page.
prev string Link to the previous page.
next string Link to the next page.

JSON example

"meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }