Методы API для добавления контактов

Основные методы для добавления/обновления контактов:

  • /v1/contact/subscribe (Тип метода: POST)
    Метод применяется для подключения форм подписки и в других случаях. Создает новые контакты, существующие обновляет. Создает в системе события для запуска сценариев. Новые контакты создаются в статусе "неподтвержденный", что позволяет реализовать double opt-in. Подробнее.
  • /v1/contacts (Тип метода: POST)
    Метод для импорта и обновления контактов. Предоставляет все возможности для управления контактами с помощью API. Контакты можно добавлять/обновлять массово или по одному, перемещать по группам. Контакты создаются сразу подтвержденными, поэтому метод не подходит для форм подписки. Также он не предназначен для запуска сценариев. Подробнее.

Методы, которые могут быть полезны для решения узкого круга специфических задач:

  • /v1/contact (Тип метода: POST)
    Метод добавления одного контакта. Всегда создает новый контакт, даже если в базе уже есть контакты с таким email или номером телефона, поэтому могут возникать дубликаты. Обновлять существующие контакты этим методом невозможно. Подробнее.
  • /v1/contact/{id} (Тип метода: PUT)
    Метод для обновления одного контакта. Новые контакты не создает. Чтобы обновить контакт этим методом надо знать id контакта в нашей системе. Подробнее.
  • /v1/contacts/upload (Тип метода: POST)
    Добавление/обновление контактов из внешнего файла. Вы можете выложить файл с контактами на своем сервере, а с помощью данного метода запускать импорт контактов из него. В запросе передается ссылка на файл. Наша система загружает файл и импортирует контакты из него. Подробнее.

Дополнительно:

  • Другие методы, создающие контакты.
    Некоторые методы API не предназначены для создания контактов. У них другие задачи. Но в некоторых ситуациях их использование приводит к созданию контакта. Подробнее.
  • Как узнать каким способом был создан контакт? Подробнее.

/v1/contact/subscribe

Тип метода: POST. Описание метода.

Метод для добавления и обновления контактов. В первую очередь предназначен для подключения форм подписки, поэтому имеет такие особенности:

  • новые конаткты создаются с неподтвержденными email-адресами
  • можно добавлять только по 1 контакту за запрос
  • контакты создаются максимально быстро, вне очереди
  • в системе создаются события для запуска сценариев
  • если переданный email-адрес или номер телефона уже есть в базе, новый контакт не создается, а обновляется существующий

Важно! Обязательно настройте процедуру подтверждения email контакта. Как это сделать описано здесь Настройка формы подписки.

С помощью данного метода можно добавлять контакты в какую-либо группу. Удалять контакты из группы этим методом нельзя.

Запуск сценариев

Метод /v1/contact/subscribe создает события, поэтому вы можете настроить и запустить автоматический сценарий для контактов, которые передаются этим методом. События создаются двух типов:

  • subscribeFromApi - название события для новых контактов
  • subscribeUpdateFromApi - название события, если контакт уже есть в системе

Каждый тип события может запускать свой сценарий. Поэтому вы можете настроить разные сценарии для новых и для ранее созданных контактов. Кроме того если у вас есть несколько форм подписки, вы можете настроить создание других событий, чтобы запускать другие сценарии. Для этого в теле запроса предусмотрен опциональный параметр formType. Его значение дописывается к названию типа события через дефис. Например, если вы передали "formType": "abc", то события будут такие:

  • subscribeFromApi-abc - для новых контактов
  • subscribeUpdateFromApi-abc - для существующих

Пример запроса с этим параметром ниже.

В каждом событии содержатся 2 параметра:

  • ContactId - числовой id контакта в нашей системе
  • EmailAddress - email-адрес. Если вы передаете только номера телефонов, этого параметра не будет

Эти параметры можно использовать в сценарии в таком виде: ${имя_параметра}. Например, ${EmailAddress}.

В качестве ключа события используется id контакта в нашей системе.

При успешной передаче запроса вы увидите в "Истории событий" примерно такие события:

Пример тела запроса

Не все элементы обязательные. Используйте те, которые вам необходимы. Сам формат и описание всех полей доступны здесь.

{
    "contact": {
        "channels": [{
            "type": "email",
            "value": "mail@example.com"
        }, {
            "type": "sms",
            "value": "380942583691"
        }],
        "firstName": "John",
        "lastName": "Smith",
        "address": {
            "town": "London",
            "region": "West",
            "address": "First str. 1",
            "postcode": "12345"
        },
        "fields": [{
            "id": "12345",
            "value": "..."
        }]
    },
    "groups": ["Subscribers"],
    "formType": "abc"
}
 
Еще один пример здесь.
URL для отправки запроса: /api/v1/contact/subscribe
 

/v1/contacts

Тип метода: POST. Описание метода.

Метод позволяет массово или по одному добавлять контакты или обновлять существующие. По сути заменяет ручной импорт контактов из файла. Подходит для синхронизации базы контактов вашей CRM с базой в eSputnik. Имеет такие особенности:

  • позволяет одним запросом добавить/обновить от 1 до 1000 контактов
  • контакты создаются сразу подтвержденные, как при импорте
  • позволяет добавлять контакт в группы и удалять из групп
  • контакты могут добавиться/обновиться не сразу, а в течение нескольких минут
  • позволяет создавать событие для запуска сценария для новых контактов

ВажноВажно! Новые контакты, переданные этим методом, создаются с подтвержденными email. Предполагается, что эти контакты уже прошли double opt-in в другой системе. Отправка рассылок контактам не прошедшим double opt-in является спамом.

Пример тела запроса

Не все элементы обязательные. Используйте те, которые вам необходимы. Формат и описание всех полей доступны здесь.

{
    "contacts": [{
        "channels": [{
            "type": "email",
            "value": "mail@example.com"
        }, {
            "type": "sms",
            "value": "380942583691"
        }],
        "firstName": "John",
        "lastName": "Smith",
        "address": {
            "town": "London",
            "region": "West",
            "address": "First str. 1",
            "postcode": "12345"
        },
        "fields": [{
            "id": 12345,
            "value": "..."
        }]
    }],
    "dedupeOn": "email",
    "customFieldsIDs": [12345],
    "groupNames": ["Customers"],
    "groupNamesExclude": ["Subscribers"],
    "restoreDeleted": false,
    "eventKeyForNewContacts": "newContact"
}

 

Массивы groupNames и groupNamesExclude используются соответственно для добавления в группы и удаления контактов из групп.
Параметр dedupeOn указывает как будет проверяться уникальность контактов. Получив запрос система будет искать в базе контакты по указанному свойству (в данном примере по email). Если контакт найден - он будет обновлен. Если не найден - будет создан новый.

URL для отправки запроса: /api/v1/contacts

Запуск сценария

При использовании данного метода события можно создать только для новых контактов. Чтобы события создавались, добавьте в тело запроса параметр eventKeyForNewContacts. Значением должна быть строка из латинских символов и цифр без пробелов. Значение будет использоваться в качестве ключа типа события и его названия.

Для каждого нового контакта система создаст событие с такими параметрами:

  • contactId - числовой id контакта в нашей системе
  • EmailAddress - email-адрес (если не передан, будет пустая строка)
  • SMS - номер телефона (если не передан, будет пустая строка)

В качестве ключей событий используется email-адрес, а если он не передан, то номер телефона.


/v1/contact

Тип метода: POST. Описание метода.

Данный метод API просто создает новый контакт. Особенности:

  • если контакт с таким email или телефоном уже есть, он не будет обновлен, а будет создан новый контакт (дубликат)
  • контакты можно создавать только по одному
  • контакты создаются сразу подтвержденными. Настроить double opt-in невозможно
  • события не создает. Сценарий запустить невозможно

Формат тела запроса и описание полей доступны здесь.

URL для отправки запроса: /api/v1/contacts

/v1/contact/{id}

Тип метода: PUT. Описание метода.

Метод только для обновления одного контакта. Особенности:

  • не позволяет создавать контакты. Только обновляет существующие
  • обновляет только по одному контакту за запрос
  • идентификация контакта возможна только по id
  • события не создает. Запустить сценарий невозможно

Формат тела запроса и описание полей доступны здесь.

URL для отправки запроса: /api/v1/contact/{id}
Вместо {id} надо подставлять числовой идентификатор контакта в нашей системе. Его можно получить, например, при помощи метода для поиска контактов по email или другим параметрам /v1/contacts GET.

Использование идентификаторов может быть неудобно. Поэтому можете обновлять контакты по email или телефону с помощью метода /v1/contacts POST.

 

/v1/contacts/upload

Тип метода: POST. Описание метода.

Добавляет или обновляет контакты из внешнего файла. Вы можете выложить файл с контактами на своем сервере, а с помощью данного метода запускать импорт контактов из него. В запросе передается ссылка на файл. Наша система загружает файл и импортирует контакты из него. Возможности метода такие же, как и у метода /v1/contacts POST за исключением того, что данные по контактам передаются не в самом запросе, а хранятся в отдельном файле.

Особенности метода:

  • контакты передаются не в теле запроса, а в отдельном файле
  • контакты создаются сразу подтвержденные, как при импорте
  • позволяет добавлять контакт в группы и удалять из групп
  • контакты могут добавиться/обновиться не сразу, а в течение нескольких минут
  • позволяет создавать событие для запуска сценария для новых контактов

​Файл должен быть в формате CSV в кодировке UTF-8. Требования к файлу и формат тела запроса описаны здесь.

Файл необходимо разместить на http-ресурсе. URL этого файла указывается в теле запроса в параметре link. Логин и пароль для доступа к файлу прописывайте в URL.

Запросы должны отправляться на этот URL: /api/v1/contacts/upload
 

Другие методы API, которые могут привести к созданию контакта

Существует несколько методов API у которых другое предназначение, но в некоторых случаях их использование приводит к созданию контакта. Во всех таких случаях контакт создается подтвержденным и не попадает ни в какие группы.

Методы для отправки сообщений (email/sms).
Если отправить сообщение получателю, которого еще нет в базе, то такой контакт создается в момент отправки. Новому контакту будет передан только канал связи (email или номер телефона). Никакие другие поля не заполняются. Ни в какие группы контакт не попадает. События не создаются.

  • /v1/message/email
  • /v1/message/sms
  • /v1/message/{id}/send
  • /v1/message/{id}/smartsend

Метод передачи заказов.
При добавлении заказа в нашу систему система проверяет есть ли в базе контакт с указанным в заказе телефоном или email-адресом. Если нет - создает новый контакт. Новому контакту будут переданы некоторые данные из заказа (если они переданы): email-адрес, номер телефона, имя и фамилия. Заметьте, что если контакт в базе уже есть, то он не будет обновлен. Имя, фамилия из заказа ему не запишутся.
При использовании этого метода в системе создаются события. Поэтому вы можете произвести некоторые операции с контактом, совершившим заказ, в сценарии. Например, можно добавить его в группу.

  • /v1/orders

Создание/обновление контакта при помощи события и сценария.
Можно передавать по API событие для запуска сценария, в котором можно настроить создание или обновление контакта. В сценариях для этого предусмотрены соответствующие блоки. В параметрах события надо передавать email контакта и строку специального формата для заполнения полей контакта.

  • /v1/event

Просмотр источника с помощью которого контакт добавлен в систему

Вы всегда можете посмотреть каким методом контакт был добавлен в систему

Источник контакта

Для этого перейдите в Контакты → Все контакты и напротив нужного контакта нажмите на лупу.

Откроется окно, где будет информация по контакту

Просмотр контакта

В графе источник вы увидите необходимую информацию.

Названия источников для различных методов

Основные методы:

  • /v1/contact/subscribe (Форма подписки)
  • /v1/contacts (Импорт контактов)
  • /v1/contact (API)
  • /v1/contacts/upload (Импорт контактов)

Методы для отправки сообщений (email/sms):

  • /v1/message/email (Одиночное сообщение)
  • /v1/message/sms (Одиночное сообщение)
  • /v1/message/{id}/send (Одиночное сообщение)
  • /v1/message/{id}/smartsend (Одиночное сообщение)

Метод передачи заказов:

  • /v1/orders (Интеграция заказов для RFM)