Address Book¶

Create a contact list¶

To create a contact list it is required to call POST /address-book-api/contact-groups, sending message parameters in the body and authorization data in the header.

Request parameters¶

Parameter	Data type	Description
fields (optional)	array[Fields]	Parameters for custom macros (fields) of contacts in the list, in addition to the main contact fields.
name	string	Contact list name.
type (optional)	string	Contact list type. Possible values: ○ `STANDARD` - standard list. ○ `STOPLIST` - the messages will not be sent to these contacts. ○ `PUSH` - list for sending push notifications. ○ `OMNI_API` - used only when sending transactional messages, you can not create a list of this type manually. Lists of this type are also not displayed when getting all lists.
autoDeleteEnabled (optional)	boolean	Automatic deletion of contacts if: ○ the contact has not been used for more than two weeks. ○ the contact was missing any data (phone, email, etc.).

Fields¶

Parameter	Data type	Description
name	string	Field name.
displayName (optional)	string	Field name in personal account.
type (optional)	string	Field type. Possible values: ○ `0` - date/time ○ `1` - `TRUE`/`FALSE` ○ `2` - number ○ `3` - text ○ `5` - object ○ `8` - date
values	array[string]	An array of possible field values, if any. For example: `["gender.male", "gender.female"]`.

Request example¶

{
  "fields": [
    {
      "displayName": "NickName",
      "name": "Nickname",
      "type": 3
    },
    {
      "displayName": "Automobile",
      "name": "Auto",
      "type": 3
    }
  ],
  "name": "TestList",
  "type": "STANDARD",
  "autoDeleteEnabled": true
}

Response parameters¶

Parameter	Data type	Description
result	string	Contact list ID.
reasons	array	An array of the errors that occurred while processing the message. To be given with `"code": "REJECTED"` only.
reasons.key	string	Error code.
reasons.ref	string	Reference to the parameter where the error has occurred.
reasons.defaultMessage	string	Message with error description.
description	string	Error description.

Response examples¶

OK

{
  "result": "3576515602081985000"
}

NULL

{
  "result": null,
  "reasons": [
    {
      "key": "name.must.be.not.null",
      "ref": "name",
      "defaultMessage": "must not be null"
    }
  ],
  "description": "Key error: (parameter: name -> must not be null)"
}

Upload contacts to the list¶

To upload contacts to the list it is required to call POST /address-book-api/contacts/batch, sending contacts parameters in the body and authorization data in the header.

Request parameters¶

Parameter	Data type	Description
zoneOffset (optional)	integer	Time offset for contact from `UTC+0` in minutes.

Request body¶

Parameter Data type Description

contactGroupId integer Contact list ID.

contacts array[Contacts] Contacts array.

duplicateCheckField
(optional)

integer

Check for the duplicate contact data.

Possible values:
○ phone - check phone number.
○ email - check email.

Contacts¶

Parameter	Data type	Description
email (optional)	string	Contact's email.
phone (optional)	string	Contact's phone number in international format, according to E.164 standard.
fields (optional)	array[Fields]	Parameters of macros (fields) of the contacts in the list, including main contact fields.
pushInfo (optional)	array[PushInfo]	Data required to receive push notifications. Only used with `PUSH` lists.

Fields¶

Parameter	Data type	Description
name	string	Field name.
displayName (optional)	string	Field name in personal account.
type (optional)	string	Field type. Possible values: ○ `0` - date/time ○ `1` - `TRUE`/`FALSE` ○ `2` - number ○ `3` - text ○ `5` - object ○ `8` - date
value	array[string]	Field value.

PushInfo¶

Parameter Data type Description

appId string Application ID.

os

integer

Operating system.

Possible values:
○ 0 - iOS.
○ 1 - Android.
○ 2 - Huawei.

pushToken string Device token.

Request example¶

{
  "contactGroupId": 3576505602081984000,
  "contacts": [
    {
      "email": "john@ggl.cm",
      "fields": [
        {
          "name": "name",
          "type": 3,
          "value": "John"
        },
        {
          "name": "surname",
          "type": 3,
          "value": "Smith"
        },
        {
          "name": "gender",
          "type": 3,
          "value": "gender.male"
        }
      ],
      "phone": "79100000000",
      "pushInfo": [
        {
          "appId": "23244532534",
          "os": 0,
          "pushToken": "23fsdivfwrq34frvsfgwgrst4334rfw"
        }
      ]
    }
  ],
  "duplicateCheckField": "phone"
}

Response parameters¶

Parameter	Data type	Description
code	string	Shows the result of message processing. 1. `OK` - processed successfully. 2. `REJECTED` - an error has occurred while processing the request.
result	array	Request result.
result.contactId	string	ID of the added contact. To be given with `"code": "OK"` only.
result.localizationKey	string	Error code.
result.fieldName	string	Reference to the parameter where the error has occurred.
result.displayName	string	Parameter name.
description	string	Error description.

Response examples¶

OK

{
  "result": [
    {
      "code": "OK",
      "result": {
        "contactId": "3379c731a0734800-337a7406f274fe80"
      }
    }
  ]
}

REJECTED

{
  "result": [
    {
      "code": "REJECTED",
      "result": {
        "localizationKey": "DUPLICATE_VALUE",
        "fieldName": "phone",
        "displayName": "Phone"
      },
      "description": "Duplicate"
    }
  ]
}

Get all contact lists¶

To get all contact lists it is required to call GET /address-book-api/contact-groups, sending lists parameters and authorization data in the header.

Request parameters¶

Parameter	Data type	Description
limit (optional)	integer	The number of rows to display in the response.
offset (optional)	integer	Line number from which the result will be displayed (offset).
name (optional)	string	Contact list name.
from (optional)	string	Filter by the creation date of the campaign - the beginning of the range. Format: `YYYY-MM-DD HH:MM:SS`.
to (optional)	string	Filter by the creation date of the campaign - the end of the range. Format: `YYYY-MM-DD HH:MM:SS`.
type (optional)	array[string]	Contact list type. Possible values: ○ `STANDARD` - standard list. ○ `STOPLIST` - the messages will not be sent to these contacts. ○ `PUSH` - list for sending push notifications.
zoneOffset (optional)	integer	Time offset for the contact from `UTC+0` in minutes.
autoDeleteEnabled (optional)	boolean	Automatic deletion of contacts if: ○ the contact has not been used for more than two weeks. ○ the contact was missing any data (phone, email, etc.).

Request example¶

curl https://api.devino.online/address-book-api/contact-groups?limit=10&offset=0 \
-h 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ=='

Response parameters¶

Parameter	Data type	Description
companyId	integer	Company ID.
contactGroupId	string	Contact list ID.
name	string	Contact list name.
creationDate	string	The date the contact list was created.
lastUpdate	string	The date the contact list was updated.
fields (optional)	array[Fields]	Parameters of macros (fields) of contacts in the list, including main contact fields.
contactsCount	integer	The number of contacts in the list.
segmentsCount	integer	The number of segments in the list.
type	string	string

Fields¶

Parameter	Data type	Description
name	string	Field name.
displayName (optional)	string	Field name in personal account.
type (optional)	string	Field type. Possible values: ○ `0` - date/time ○ `1` - `TRUE`/`FALSE` ○ `2` - number ○ `3` - text ○ `5` - object ○ `8` - date
values	array[string]	An array of possible field values, if any. For example: `["gender.male", "gender.female"]`.
isDefault	boolean	Whether the field is displayed by default.

Response example¶

{
  "result": [
    {
      "contactGroupId": "23556345674567625",
      "companyId": 452345234,
      "name": "ContactsList",
      "creationDate": "2022-10-22T18:14:21",
      "lastUpdate": "2022-10-22T18:14:21",
      "fields": [
        {
          "name": "name",
          "displayName": "Name",
          "type": 3,
          "isDefault": true
        }
        {
          "name": "gender",
          "displayName": "Gender",
          "type": 3,
          "isDefault": true,
          "values": [
            "gender.male",
            "gender.female"
          ]
        },
        {
          "name": "country",
          "displayName": "Country",
          "type": 3,
          "isDefault": true
        },
        {
          "name": "city",
          "displayName": "City",
          "type": 3,
          "isDefault": true
        }
      ],
      "contactsCount": "34234",
      "segmentsCount": "2",
      "type": "STANDARD",
      "autoDeleteEnabled": false
    }
  ]
}

Get all contacts from the list¶

To get all contacts from the list it is required to call GET /address-book-api/contacts/http/range, sending contact parameters and authorization data in the header.

Request parameters¶

Parameter	Data type	Description
contactGroupId	string	Contact list ID.
descOrder (optional)	boolean	Sorting order. Possible values: ○ `false` - ascending (`asc`) ○ `true` - descending (`desc`)
limit (optional)	integer	The number of rows to display in the response.
offset (optional)	integer	Line number from which the result will be displayed (offset).
pushToken (optional)	string	Device token.
queryName (optional)	string	Query field for the filter.
queryOperator (optional)	string	Query operator for the filter. Possible values: ○ `ex` - exists (`EXISTS`) ○ `eq` - equals (`EQUALS`) ○ `neq` - does not equal (`NOT_EQUALS`) ○ `gt` - greater than (`GREATER_THAN`) ○ `lt` - less than (`LESS_THAN`) ○ `ngt` - not greater than (`NOT_GREATER_THAN`) ○ `nlt` - not less than (`NOT_LESS_THAN`) ○ `inc` - contains (`CONTAINS`) ○ `ninc` - does not contain (`NOT_CONTAINS`) ○ `sw` - starts with (`STARTS_WITH`) ○ `ew` - ends with (`ENDS_WITH`) ○ `nsw` - does not start with (`NOT_STARTS_WITH`) ○ `new` - does not end with (`NOT_ENDS_WITH`) ○ `range` - in range (`RANGE`) ○ `nrange` - not in range (`NOT_IN_RANGE`) ○ `ma` - matches (`MATCHES`) ○ `nma` - does not match (`NOT_MATCHES`)
queryValue (optional)	string	The query value for the filter.
segmentId (optional)	string	Segment ID.
sortByField (optional)	string	Field to sort by.
zoneOffset (optional)	integer	Time offset for the contact from `UTC+0` in minutes.
subscriptionChannel (optional)	string	Subscription channel. Possible values: `EMAIL`, `FLASHCALL`, `HLR`, `PUSH`, `SMS`, `VIBER`, `VK`, `VOICE`, `WHATSAPP`.
subscriptionState (optional)	string	Subscription type. Possible values: ○ `ALL` - all contacts. ○ `SUBSCRIBED` - subscribed contacts. ○ `UNSUBSCRIBED` - unsubscribed contacts.

Request example¶

curl https://api.devino.online/address-book-api/contacts/http/range?limit=10&offset=0&contactGroupId=3576515602081985000 \
-h 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
-h 'Content-Type: application/json'
-h 'Accept: application/json'

Response parameters¶

Parameter	Data type	Description
companyId	integer	Company ID.
contactGroupId	integer	Contact list ID.
contactId	string	Contact ID.
creationDate	string	The date the contact was created.
last update	string	The date the contact was updated.
fields	array[Fields]	Parameters of macros (fields) of contacts in the list, including main contact fields.
email	string	Contact's email.
phone	string	Contact's phone number.
unsubscribedData	array[UnsubscribedData]	Contact unsubscription data.
pushInfo	array[PushInfo]	Data required to receive push notifications.

Fields¶

Parameter	Data type	Description
name	string	Field name.
displayName	string	Field name that will be displayed in the personal account.
type	integer	Field type. Possible values: `0` - date/time `1` - `TRUE`/`FALSE` `2` - integer `3` - text `5` - object `8` - date
value	array[string]	Field value.
values	array[string]	Array of possible field values, if it is needed. For example: `["gender.male", "gender.female"]`.
isDefault	boolean	Whether the field is displayed by default.

UnsubscribedData¶

Parameter	Data type	Description
channelList	array[UnsubscribedChannel]	Unsubscription channel data.
companyId	integer	Company ID.
data	string	Unsubscription data (phone number, email or device token).
dataType	string	Unsubscription data type. Possible values: `EMAIL`, `PHONE`, `TOKEN`.
updatedAt	string	The date the subscription was updated.

UnsubscribedChannel¶

Parameter Data type Description

channel

string

Unsubscription channel.

Possible values: EMAIL, FLASHCALL, HLR, PUSH, SMS, VIBER, VK, VOICE, WHATSAPP.

unsubscribedAt integer Unsubscription date.

unsubscribedType string Unsubscription type. Only the value SPAM is possible.

Response example¶

{
  "result": [
    {
      "contactId": "31a24ce55d4a8e00-31a251fea18b9280",
      "companyId": 112233,
      "contactGroupId": "3576515602081985000",
      "creationDate": "2020-10-20 09:01:05",
      "lastUpdate": "2020-10-20 09:01:05",
      "phone": "79100000000",
      "email": "valya@yandex.ru",  
      "fields": [
        {
          "name": "name",
          "displayName": "Name",
          "type": 3,
          "isDefault": true
        },
        {
          "name": "surname",
          "displayName": "Last name",
          "type": 3,
          "isDefault": true
        },
        {
          "name": "gender",
          "displayName": "Gender",
          "type": 3,
          "isDefault": true,
          "values": [
            "gender.male",
            "gender.female"
          ]
        }
      ],
      "unsubscribedData": [
        {
          "companyId": 112233,
          "data": "valya@yandex.ru",
          "dataType": "EMAIL",
          "channelList": [
            {
              "channel": "EMAIL",
              "unsubscribedAt": "2020-10-21T08:13:55",
              "unsubscribedType": "SPAM"
            }
          ],
          "updatedAt": "2020-10-21 08:13:55"
        }
      ]
    }
  ]
}

Delete contact list¶

To delete one or multiple contact lists it is required to call DELETE /address-book-api/contacts-groups, sending contact lists ID and authorization data in the header.

Request parameters¶

Parameter	Data type	Description
ids	array[integer]	Contact list ID. Several values can be transmitted.

Request example¶

curl -X DELETE https://api.devino.online/address-book-api/contact-groups?ids=5435476543542&ids=435467586654&ids=4325364758 \
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Response parameters¶

Parameter	Data type	Description
result	array	An array with request results. Every contact list will have its own result.
result.code	string	Shows the result of request processing. 1. `OK` - processed successfully. 2. `REJECTED` - an error has occurred.
result.result	string	Contact list ID.
result.description	string	Message with error description. To be given with `"code": "REJECTED"` only.
reasons	array	An array of errors that occurred while processing the message. To be given with `"code": "REJECTED"` only.
reasons.key	string	Error code.
reasons.ref	string	Reference to the parameter where the error has occurred.

Response example¶

{
  "result": [
    {
      "code": "OK",
      "result": "5435476543542"
    },
    {
      "code": "OK",
      "result": "435467586654"
    },
    {
      "code": "OK",
      "result": "4325364758"
    }
  ]
}

Segments¶

Contact lists can be divided into segments. Segments allow you to filter contacts from the list.

Attention

One contact list can have maximum of 20 segments.

Create segment¶

To create one contact list segment it is required to call POST /address-book-api/segments, sending segment parameters in the request body and authorization data in the header.

Request parameters¶

Parameter	Data type	Description
contactGroupId	integer	Contact list ID.
name	string	Segment name. Segment names can not be repeated within the same contact list.
query	array[object]	Contact selection parameters for the segment.

Query¶

Parameter	Data type	Description
filterOperator	string	Filters operator. Available values: ○ `AND` - and ○ `OR` - or ○ `EXCLUDE` - exclude
filterElements	array[object]	Filters data. The array can contain maximum of 2 objects.
name (optional)	string	The contact attribute name for selecting contacts.
operator (optional)	string	Contact filter operator.
value (optional)	string	Contact attribute value for selecting contacts.

Request example¶

Important

When creating a request, it is important to consider the following conditions::

There can only be two objects (filters) in the filterElements array.
If the filterOperator parameter is used, then the name, operator, value parameters will be specified only in the nested object inside the filterElements array.
If the name, operator, value parameters are used, the filterOperator parameter must be specified in the same object to validate the request. However, it will not be used in the filters themselves. Read the comment to the request examples for a better understanding.

For convenience, it is better to use no more than three filters per segment.

Without filterElements

The "filterOperator": "AND" parameter in this case is needed only for request validation. It will not be used in the segment filters.

{
  "contactGroupId": 3648143200368952320,
  "name": "segmentName",
  "query": [
    {
      "filterOperator": "AND",
      "filterElements": [
        {
          "name": "name",
          "operator": "sw",
          "value": "John"
        }
      ]
    }
  ]
}

With one filterElements

This request contains two filters: contacts with a phone number starting with 7999 OR with the name John will be added to this segment. The "filterOperator": "AND" parameters in this case are needed only for request validation. They will not be used in the segment filters.

{
  "contactGroupId": 3648143200368952320,
  "name": "segmentName",
  "query": [
    {
      "filterOperator": "OR",
      "filterElements": [
        {
          "filterOperator": "AND",
          "filterElements": [
            {
              "name": "name",
              "operator": "sw",
              "value": "John"
            }
          ]
        },
        {
          "filterOperator": "AND",
          "filterElements": [
            {
              "name": "phone",
              "operator": "eq",
              "value": "79995854330"
            }
          ]
        }
      ]
    }
  ]
}

With two filterElements

This request contains three filters: contacts with a phone number starting with 7999 OR with the name John OR with the surname