Методы Snov.io API

Многие функции Snov.io доступны в интерфейсе REST API. Интеграция со Snov.io API позволяет пользоваться Snov.io Email Finder, Snov.io Email Verifier и даже инструментом «Триггерные рассылки».

Обратите внимание, что пропускная способность API ограничена 60 запросами в минуту.

Обзор:

  1. Как аутентифицировать запросы
  2. Методы API:

Аутентификация

Для аутентификации будущих запросов необходимо сгенерировать токен доступа. Отправляя запрос, укажите токен доступа в поле авторизации. Пример:

Snov.io API

Запрос

auth

Входящие параметры

grant_type    Всегда  “client_credentials“.
client_id Узнать ваш id можно в настройках аккаунта https://app.snov.io/api-setting.
client_secret Узнать секретный ключ можно в настройках аккаунта https://app.snov.io/api-setting.

Примеры кода

 auth example php

auth example python

Ответ

Snov.io API

Параметры ответа

access_token Ваш новый токен доступа.
token_type Всегда Bearer
expires_in Срок действия токена (в секундах).

Методы API

В настоящее время в вашем распоряжении около дюжины API методов:

Подсчет адресов

Бесплатно

Этот метод API позволяет узнать, какое количество email-адресов с определенного домена содержится в нашей базе данных. Услуга абсолютно бесплатна, кредиты не используются.

Запрос

count

Входящие параметры

domain Имя домена, количество адресов с которого вы хотите узнать.

Примеры кода

count example php

count example python

Ответ

Snov.io API

Параметры ответа

domain Имя домена, количество адресов с которого вы хотите узнать.
webmail Будет true, если домен, который вы выбрали, является сайтом электронной почты.  
result Общее количество email-адресов, найденных нами для этого домена. Мы не можем предоставить результаты для сайтов электронной почты, потому для них результат всегда 0.

1 кредит за 10 адресов/контактов

Укажите доменное имя, и Snov.io предоставит вам все email-адреса, найденные на этом домене. Если в нашей базе данных есть дополнительная информация о человеке, которому принадлежит email-адрес, она также будет добавлена. На каждый запрос возвращается до 100 адресов. Запрос, по которому не вернулся хотя бы один адрес, не оплачивается.

Запрос

Входящие параметры

domain Имя домена, на котором вы хотите найти email-адреса. Например, snov.io.
type Может содержать разные значения: all, personal или generic.

Общий адрес электронной почты связан с функцией сотрудников, которые его используют, например contact@snov.io.

Личный адрес электронной почты — это адрес конкретного сотрудника компании.

limit Используйте это поле, чтобы указать количество адресов, которые хотите получить. Каждый запрос возвращает до 100 адресов.
lastId  Чтобы собрать больше email-адресов, чем указано во входящем параметре Limit, в следующем запросе укажите id последнего собранного адреса из предыдущего запроса. Таким образом, ранее собранные email-адреса будут пропущены.
Обратите внимание, что параметр lastId — обязателен. Значение по умолчанию — 0.

Примеры кода

Ответ

Параметры ответа

domain Имя домена, для которого API нашел email-адреса.
webmail Будет true, если домен, который вы выбрали, используется службой электронной почты.
result Количество email-адресов, найденных нами для этого домена. Мы не можем предоставить результаты для сайтов электронной почты, потому для них результат всегда 0.
limit Максимальное количество адресов, возвращенных в ответ на запрос.
companyName Название компании, использованное для поиска адресов.
emails Адреса с домена, найденные при поиске.
email Конкретный адрес электронной почты, полученный в результате поиска.
type Может иметь значения prospect или email. Если возвращенное значение prospect, значит Snov.io нашел дополнительную информацию о владельце email-адреса.
status Статус проверки email-адреса. Может быть verified или notVerified.
firstName Имя владельца email-адреса.
lastName Фамилия владельца email-адреса.
position Должность, которую владелец email-адреса занимает в настоящий момент.
sourcePage Страница, на которой были найдены персональные данные.
lastId Id последнего собранного email-адреса из предыдущего ответа.

Проверка адресов

Бесплатно

Убедитесь, что полученные адреса электронной почты действительны и письмо, отправленное по ним, может быть доставлено. Бесплатно. Конечная точка API вернет результаты проверки адреса. Если мы не проверяли этот email-адрес ранее, API вернет идентификатор «not_verified», и кредиты за такой адрес не снимутся. Используйте метод Добавить адреса для проверки, чтобы передать этот адрес на проверку, после чего вы сможете получить результаты проверки, используя эту конечную точку.

Запрос

email verifier

Входящие параметры

emails Email-адреса, которые нужно проверить.

Примеры кода

email verifier

email verifier

Ответ

Snov.io API

Этот метод вернет данные по каждому адресу, указанному в запросе. Ответ содержит статус и результаты проверки адреса.

Параметры ответа

status Статус проверки адреса. Содержит идентификатор и описание.
identifier Может содержать следующие значения: complete, in_progress, или not_verified. Если идентификатор not_verified, data будет пустым.
description В этом поле будет текстовое описание статуса проверки.
data Содержит дополнительную информацию о результатах проверки: email, isValidFormat, isWebmail, isGibberish.
 email Email-адрес, который проверялся.
isValidFormat Будет true, если формат адреса правильный, то есть содержит допустимые символы в правильном порядке.
isDisposable Будет true, если установлено, что адрес предоставлен одноразовой службой электронной почты.
isWebmail Будет true, если адрес предоставлен службой электронной почты.
isGibberish Будет true, если адрес сгенерирован автоматически.
smtpStatus Возможные ответы: valid, not_valid, greylistedили unknown (непроверяемый). Вы можете узнать больше об email-статусах здесь.
Если smtpStatus «greylisted», это значит, что мы временно не можем верифицировать этот email-адрес, но продолжим попытки.
Вы можете повторно отправить этот запрос API после небольшой паузы (как правило, от 15 минут до 1 часа), чтобы получить корректные результаты.
Обратите внимание, что мы не снимаем плату за статус «greylisted» до того момента, пока не сможем точно определить SMTP-статус как «valid» или «not_valid».

Добавить адреса для проверки

0,5 кредита за адрес

Если вы проверяете адрес в первый раз, отправьте его на проверку при помощи этого метода API. Сделав это, вы получите результаты проверки в инструменте Проверка адресов.

Запрос

add emails

Входящие параметры

emails Список адресов, которые необходимо добавить в очередь на проверку. Каждый запрос может содержать до 10 адресов.

Примеры кода

api

add emails

Response

Snov.io API

Если адрес электронной почты добавлен в очередь, метод вернет «sent»:true.

Поиск адресов

1 кредит за запрос

Этот метод API ищет адреса по имени и фамилии человека и доменному имени. Если адреса нет в нашей базе данных, мы не сможем сразу же предоставить вам результаты поиска. Чтобы ускорить процесс, используйте метод «Добавить имена для поиска адресов», чтобы отправить адрес на проверку. После чего воспользуйтесь инструментом «Поиск адресов» еще раз.

Запрос

email finder

Входящие параметры

firstName Имя владельца email-адреса.
lastName Фамилия владельца email-адреса.
domain Доменное имя компании, использованное в адресе электронной почты.

Примеры кода

email finder

email finder

Ответ

Snov.io API

Параметры ответа

status Используйте значения этого объекта, чтобы определить статус процесса.
identifier Может содержать следующие значения: complete, in_progress, или not_found. При идентификаторе not_found ответ не будет содержать email-адреса.
description Текстовое описание статуса поиска адреса.
data Содержит результаты поиска.
firstName Имя владельца email-адреса.
lastName Фамилия владельца email-адреса.
emails Массив адресов электронной почты и их статусов. Значение emailStatus может содержать: valid или unknown.

Добавить имена для поиска адресов

1 кредит за запрос

Если Snov.io не находит искомые адреса в своей базе данных и не может их найти с помощью инструмента Поиск адресов, можно попробовать отправить запрос на поиск адреса, используя этот метод. Если адрес найден, вы можете получить его с помощью бесплатного повторного запроса в инструменте Поиск адресов.

Запрос

add names

Входящие параметры

firstName Имя владельца email-адреса.
lastName Фамилия владельца email-адреса.
domain Доменное имя компании, использованное в адресе электронной почты.

Примеры кода

api

add names

Ответ

Snov.io API

Если адрес электронной почты добавлен в очередь, метод вернет «sent»:true.

Найти профиль по адресу

1 кредит за запрос

Укажите адрес электронной почты, и Snov.io вернет всю связанную с владельцем адреса информацию, которая есть в нашей базе данных.
Если нам не удастся найти информацию о владельце адреса в нашей базе данных, оплата за запрос не снимется.

Запрос

get profile

Входящие параметры

email Адрес электронной почты, принадлежащей лицу, дополнительную информацию о котором вы хотите найти.

Примеры кода

get profile

get profile

Ответ

Параметры ответа

id Уникальный идентификатор профиля.
source Источник полученных персональных данных.
name Полное имя владельца email-адреса.
firstName Имя.
lastName Фамилия.
logo Аватар профиля.
industry Отрасль, указанная в источнике данных.
country Страна, указанная в источнике данных.
locality Местоположение, указанное в источнике данных.
social Ссылки на профили в соцсетях.
currentJobs Массив, который содержит информацию о текущей должности лица.
previousJobs Массив, который содержит информацию о предыдущих должностях лица.
lastUpdateDate Дата последнего обновления профиля в базе данных.

Добавить контакты в список

Бесплатно

Добавьте контакт в определенный список. Этот метод используется, когда необходимо автоматизировать процесс добавления контактов в списки, для которых идет рассылка. Таким образом, после добавления контакта в выбранный список рассылка для него начнется автоматически.

Запрос

Add Prospect to List

Входящие параметры

email (Required) Адрес электронной почты контакта.
fullName Полное имя контакта.
firstName Имя контакта.
lastName Фамилия контакта.
country Страна контакта. Список стран представлен здесь. Просим вас использовать только страны из списка.
locality Местоположение контакта.
position Должность контакта.
companyName Название компании контакта.
companySite Сайт компании контакта. Пожалуйста, используйте формат http://example.com.
updateContact Обновляет информацию о существующем контакте. Может содержать true, или false. Если trueи контакт с таким адресом электронной почты уже есть в одном из списков, система обновит существующий профиль. Если false, система не обновит существующий профиль.
customFields[phone number] Вы можете добавить кастомные поля. Укажите название кастомного поля в [скобках].
social[linkedin] Ссылка на профиль контакта в соцсетях. Укажите название социальной сети в [скобках] (LinkedIn, Facebook или Twitter).
listId (Required) Идентификатор списка, к которому принадлежит контакт.

Примеры кода

api

Add Prospect to List

Ответ

Snov.io API

Параметры ответа

success Будет true, если контакт был добавлен в список.
id Добавленный идентификатор контакта.
added Будет true, если контакт был добавлен в список.
updated Будет true, если данные существующего контакта обновились.
errors При добавлении контакта в список возникла ошибка.

Найти контакт по id

Бесплатно

Найдите контакты в списках по id. Зная id контакта, можно получить полную информацию о нем, включая списки и рассылки, в которые он включен.

Запрос

Find Prospect by ID

Входящие параметры

Id (Required) Id контакта. Его можно увидеть в ответе, когда вы добавляете контакт с помощью метода API Добавить контакты в список или в адресной строке, когда просматриваете страницу контакта (пример).

Примеры кода

Find Prospect by ID

Find Prospect by ID

Ответ

Snov.io API

Параметры ответа

success Будет true, если контакт найден.
id Уникальный идентификатор профиля.
name Полное имя контакта.
firstName Имя контакта.
lastName Фамилия контакта.
industry Отрасль, указанная в профиле контакта.
locality
Местоположение контакта.
country Страна контакта.
social Ссылки на профили контакта в соцсетях.
currentJobs Массив содержит информацию о текущей должности контакта.
previousJobs Массив содержит информацию о предыдущих должностях контакта.
lastUpdateDate Дата последнего обновления профиля.
lists Списки, в которые был добавлен контакт.
campaigns Список рассылок запущенных для контакта. Содержит краткую статистику, например: статус, количество отправленных и открытых писем, и ответов на них.

Найти контакт по email-адресу

Бесплатно

Ищите контакты в списках по адресу электронной почты. При поиске по email-адресу вы получаете список всех контактов, привязанных к email-адресу. Каждый элемент в списке содержит полную информацию о контакте, в том числе списки и рассылки, в которые он включен.

Запрос

Find Prospect by Email

Входящие параметры

email (Required) Адрес электронной почты контакта.

Примеры кода

Find Prospect by Email

Find Prospect by Email

Ответ

Snov.io API

Параметры ответа

success Будет true, если контакт найден.
id Уникальный идентификатор профиля.
name Полное имя контакта.
firstName Имя контакта.
lastName Фамилия контакта.
industry Отрасль, указанная в профиле контакта.
locality
Страна контакта.
country Местоположение контакта.
social Ссылки на профили контакта в соцсетях.
currentJobs Массив содержит информацию о текущей должности контакта.
previousJobs Массив содержит информацию о предыдущих должностях контакта.
lastUpdateDate Дата последнего обновления профиля.
lists Списки, в которые был добавлен контакт.
campaigns Список рассылок запущенных для контакта. Содержит краткую статистику, например: статус, количество отправленных и открытых писем, и ответов на них.

Изменить статус получателя

Бесплатно

Измените статус получателя конкретной рассылки.

Запрос

Change recipient status

Входящие параметры

email (Required) Адрес электронной почты контакта.
campaign_id (Required) Id рассылки. Его можно увидеть в адресной строке при просмотре информации о рассылке (показать пример).
status (Required) Новый статус получателя. Возможные статусы: «Active», «Paused», «Finished», «Unsubscribed», «Auto-replied», «Replied», «Replied from another email». Если получателю присвоен статус «Finished» или «Moved», такой статус изменить нельзя.

Примеры кода

Change recipient status

Change recipient status

Ответ

API methods

Параметры ответа

Метод вернет success: true“, если статус контакта был изменен. В случае ошибки метод вернет success: falseс описанием ошибки.

Добавить ссылку на профиль для поиска контакта

1 кредит за запрос

Находите контакты по профилям в соцсетях. Для дальнейшего получения результатов поиска применяйте метод «Собрать контакт по ссылке на профиль».

Запрос

api

Входящие параметры

URL Ссылка на профиль контакта в соцсетях. Укажите название социальной сети в [таких скобках] (LinkedIn или Twitter).

Примеры кода

api

api

Ответ

Response

Параметры ответа

success Будет true, если контакт был добавлен в поисковый список.
message При добавлении контакта в список возникла ошибка.

Собрать контакт по ссылке на профиль

Бесплатно

После использования метода «Добавить ссылку на профиль для поиска контакта», используйте этот метод для получения полной найденной информации о нем включая адрес электронной почты.

Запрос

api

Входящие параметры

URL Ссылка на профиль контакта в соцсетях. Укажите название социальной сети в [таких скобках] (LinkedIn или Twitter).


Примеры кода

api

api

Ответ

api

Параметры ответа

success Будет true, если контакт найден.
id Уникальный идентификатор профиля.
name Полное имя контакта.
firstName Имя контакта.
lastName Фамилия контакта.
industry Отрасль, указанная в профиле контакта.
country Страна контакта.
locality Местоположение контакта.
skills Навыки контакта.
social Ссылки на профили контакта в соцсетях.
currentJobs Массив содержит информацию о текущей должности контакта.
previousJobs Массив содержит информацию о предыдущих должностях контакта.
lastUpdateDate Дата последнего обновления профиля.
emails
Email-адрес контакта и его актуальный статус.

Найти кастомные поля контактов

Бесплатно

Этот метод возвращает список всех кастомных полей, созданных пользователем, в том числе названия полей, параметры, определяющие обязательное это поле или нет, и тип информации внутри поля.

Запрос

api

Входящие параметры

Для этого метода отсутствуют необходимые входящие параметры

Примеры кода

Методи API

Методи API

Ответ

api

Параметры ответа

key Ключ поля в массиве customFields.
label Название поля.
required Будет true если кастомное поле обязательное.
type Тип данных кастомного поля (строка, число или дата).

Просмотр списков пользователя

Бесплатно

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

Запрос

api

Входящие параметры

Для этого метода отсутствуют необходимые входящие параметры

Примеры кода

Методи API

Методи API

Ответ

api

Параметры ответа

Id Уникальный id списка пользователя.
Name Название списка.
Contacts Количество контактов в списке.
isDeleted Статус списка. Возвращает “true“, если список был удален.
CreationDate Дата создания списка (включает информацию о дате, времени и часовом поясе).
deleteDate
Содержит дату удаления, если список был удален (включая время и часовой пояс).

Проверка баланса

Бесплатно

Используйте этот метод для проверки баланса кредитов на вашем счету.

Запрос

api

Входящие параметры

Для этого метода отсутствуют необходимые входящие параметры

Примеры кода

Методи API

Методи API

Ответ

api

Параметры ответа

Balance
Текущий баланс пользователя в кредитах.

Просмотр контактов из списка

Бесплатно

Этот метод возвращает все данные о контактах в указанном списке, такие как email-адрес и их статус.

Запрос

Request

Входящие параметры

listId (Required)
Уникальный id списка.
page Вы можете выбрать с какой страницы списка начать поиск. Это поле необязательно.
perPage Выберите страницу списка, на которой следует закончить поиск. Это поле необязательно. Максимальное значение — 100.

Примеры кода

Методи API

Методи API

Ответ

Обратите внимание: результаты отображаются в обратном порядке, от последнего контакта к первому.

api

Параметры ответа

list Массив с информацией о списке и контактах, которые он содержит.
name Название списка.
contacts Количество контактов в списке.
creation_date Дата создания списка (включая время и часовой пояс).
emailsCount Количество email-адресов в списке.
prospects Все контакты в списке.
id Уникальный id контакта.
name Полное имя контакта.
emails Список email-адресов, принадлежащих контакту.

Список контактов, для которых рассылка завершена

Бесплатно

Этот метод возвращает список контактов, для которых рассылка завершена.

Запрос

new api

Входящие параметры

campaignId

(Required)

Id рассылки для получения списка контактов.

Примеры кода

new api

api

Ответ

api

Параметры ответа

id
Уникальный id.
prospectId Id контакта.
userName Полное имя контакта.
userEmail Email-адрес контакта.
campaign Название рассылки.

Просмотр ответов на рассылку

Бесплатно

Этот метод возвращает информацию об ответах на письма со всеми данными, в том числе именем контакта, id, названием рассылки и др.

Запрос

api

Входящие параметры

campaignId

(Required)

Id рассылки для просмотра ответов.

api

api

Ответ

api

Параметры ответа

campaignId
Id рассылки.
campaign Название рассылки.
prospectName Полное имя контакта.
emailSubject Тема письма.
emailBody Содержание письма.

Информация об открытиях писем в рассылке

Бесплатно

Этот метод показывает информацию об открытых письмах в рассылке.

Запрос

api

Входящие параметры

campaignId

(Required)

Id рассылки для просмотра ответов.

Примеры кода

api

api

Ответ

api

Параметры ответа

campaignId
Id рассылки.
campaign Название рассылки.
prospectName Полное имя контакта.
emailSubject Тема письма.
visitedAt
Время открытия.

Проверка переходов по ссылкам

Бесплатно

Этот метод возвращает информацию о всех получателях в рассылке, которые перешли по ссылке в одном или более письме.

Запрос

api

Входящие параметры

campaignId

(Required)

Id рассылки для просмотра ответов.

Примеры кода

api

api

Ответ

api

Параметры ответа

campaignId
Id рассылки.
campaign
Название рассылки.
prospectName Полное имя контакта.
prospectEmail Email-адрес контакта.
emailSubject Тема письма.
emailBody
Содержание письма.
visitedAt Время открытия.


Просмотр рассылок пользователя

Бесплатно

Этот метод предоставляет список всех рассылок пользователя.

Запрос

Методи API

Входящие параметры

Для этого метода отсутствуют необходимые входящие параметры

Примеры кода

api

api

Ответ

api

Параметры ответа

id
Id рассылки.
campaign
Название рассылки.

Больше информации на странице API.