Ресурсы API для добавления контактов

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

• Subscribe contact (Тип метода: POST)

  Метод применяется для подключения форм подписки и в других случаях. Создает новые контакты, существующие обновляет. Создает в системе события для запуска сценариев. Новые контакты создаются в статусе "неподтвержденный", что позволяет реализовать double opt-in. Подробнее.

• Add/update contacts (Тип метода: POST)

  Метод для импорта и обновления контактов. Предоставляет все возможности для управления контактами с помощью API. Контакты можно добавлять/обновлять массово или по одному, перемещать по группам. Контакты создаются сразу подтвержденными, поэтому метод не подходит для форм подписки. Также он позволяет создавать событие для запуска сценария новым контактам (за исключением контактов, которые ранее были добавлены, а потом удалены). Подробнее.

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

• Add contact (Тип метода: POST)

  Метод добавления или обновления одного контакта. Подробнее.

• Update contact (Тип метода: PUT)

  Метод для обновления одного контакта. Новые контакты не создает. Чтобы обновить контакт этим методом надо знать id контакта в нашей системе. Подробнее.

• Add/update contacts from external file (Тип метода: POST)

  Добавление/обновление контактов из внешнего файла. Вы можете выложить файл с контактами на своем сервере, а с помощью данного метода запускать импорт контактов из него. В запросе передается ссылка на файл. Наша система загружает файл и импортирует контакты из него. Подробнее.
• Attach contact to static segment (Тип метода: POST)

• Attach contact to static segment (Тип метода: POST)

  Метод для добавления контактов в группы типа “Список”. Подробнее.

• Delete from static segment (Тип метода: POST)

  Метод для удаления контактов из групп типа “Список”. Подробнее.

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

• Другие методы, создающие контакты.

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

• Как узнать каким способом был создан контакт? Подробнее.

Subscribe contact

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

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

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

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

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

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

• 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

Add/update contacts

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

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

• позволяет одним запросом добавить/обновить от 1 до 3000 контактов;
• контакты создаются сразу подтвержденные, как при импорте;
• позволяет добавлять контакты в группы и удалять из групп;
• контакты могут добавиться/обновиться не сразу, а в течение нескольких минут;
• позволяет создавать событие для запуска сценария для новых контактов;
• в ответе приходит asyncSessionId, с помощью которого методом v1/importstatus/ можно получить статус импорта и id контактов.

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

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

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

Если массив объектов contacts содержит externalCustomerId, в поиске используется externalCustomerId, а параметр dedupeOn игнорируется.

Массивы groupNames и groupNamesExclude используются соответственно для добавления в группы и удаления контактов из групп.

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

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

Если ваш API запрос сформирован правильно, в ответ возвращается код HTTP 200.

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

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

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

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

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

Add contact

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

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

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

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

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

Update contact

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

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

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

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

URL для отправки запроса: /api/v1/contact/{id}

Вместо {id} надо подставлять числовой идентификатор контакта в нашей системе. Его можно получить, например, при помощи метода для поиска контактов по email или другим параметрам Search contacts.

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

Add/update contacts from external file

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

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

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

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

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

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

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

Attach contact to static segment

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

Добавляет контакты в группы типа “Список” по contactId или externalCustomerId (в запросе может быть только один из этих параметров). Максимальное количество контактов в одном запросе — 500. 

URL для отправки запроса: /api/v1/group/{id}/contacts/attach

Вместо {id} надо подставить числовой идентификатор группы в нашей системе. 

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

Delete from static segment 

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

Удаляет контакты из группы типа “Список”. Идентификаторы для добавления — contactId или externalCustomerId (в запросе может быть только один параметр из этих параметров).

Если не указать идентификаторы, все контакты будут удалены из группы.

URL для отправки запроса: /api/v1/group/{id}/contacts/detach

Вместо {id} надо подставлять числовой идентификатор группы в нашей системе. 

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

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

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

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

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

• Send email message
• Send SMS message
• Send prepared message

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

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

При использовании этого метода в системе создаются события. Поэтому вы можете произвести некоторые операции с контактом, совершившим заказ, в сценарии. Например, можно добавить его в группу.

• Add orders

Создание/обновление контакта при помощи события и сценария.

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

• Generate event

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

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

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

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

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

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

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

• Subscribe contact (Форма подписки)
• Add/update contacts (Импорт контактов)
• Add contact (API)
• Add/update contacts from external file (Импорт контактов)

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

• Send email message (Одиночное сообщение)
• Send SMS message (Одиночное сообщение)
• Send prepared message (Одиночное сообщение)

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

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