Snov.io API methods

You can easily use many of Snov.io’s features through our REST API. Integration with Snov.io API allows you to use Snov.io Email Finder, Snov.io Email Verifier and even Email Drip Campaigns tool.

Please note that the API rate is limited to 60 requests per minute.

Outline:

      1. How to authenticate requests
      2. API methods:

Authentication

To authenticate future requests you need to generate an access token. While making a request, paste this access token in the Authorization field. Here is an example:

Snov.io API

Request

auth

Input Parameters

grant_type    will always be “client_credentials
client_id your id is available in the account settings  https://app.snov.io/api-setting
client_secret your secret key is available in the account settings  https://app.snov.io/api-setting

Code examples

 auth example php

auth example python

Response

Snov.io API

Output Parameters

access_token your new access token
token_type will always be Bearer
expires_in token expiration time (in seconds)

API methods

Currently, we provide almost a dozen API methods: 

Email count

This API method helps you know the number of email addresses from a particular domain in our database. It is absolutely free.

Request

count

Input Parameters

domain the name of the domain for which you’d like to know the number of emails in our database

Code examples

count example php

count example python

Response

Snov.io API

Output Parameters

domain the name of the domain for which you’d like to know the number of emails in our database
webmail is “true” if the domain you’re searching is webmail
result a total number of email addresses found for this domain. We can’t provide results for webmail domains, so the result for webmail will always be 0

Give us a domain name and we will return all the email addresses on the domain. It costs 1 credit per 10 emails/prospects. Any additional information about the email owner available in the database will be added too. Each response returns up to 100 emails. If it does not return at least one email, you will not be charged for the request.

Request

Input Parameters

domain the name of the domain from which you want to find the email addresses. E.g. “snov.io”
type can include different values – “all“, “personal” or “generic“;

a generic email address is a role-based email address, for example – contact@snov.io;

a personal email address is the email of the actual person working at the company

limit set the limit to specify the number of email addresses to return;

each response returns up to 100 email addresses

lastId  to collect more emails than is set in your Limit input parameter, in your next request indicate the id of the last collected email address from the previous request. This way, previously collected emails will be skipped.
Note that lastId is a required parameter. The default value is
0).

Code examples

Response

Output Parameters

domain the domain name for which the API has provided the email addresses
webmail is “true” if the domain you’re searching is webmail
result the number of email addresses we have found for this domain. We can’t provide results for webmail domains, so the result for webmail will always be 0
limit indicates the maximum number of email addresses to return
companyName the company name used to find the email addresses
emails the array of domain emails retrieved in the search
email a specific email address received in a search
type can contain “prospect” or “email” values;

if the returned type is “prospect”, Snov.io has found the additional information about the email owner

status email’s verification status; can be “verified” or “notVerified”
firstName the email owner’s first name
lastName the email owner’s last name
position the email owner’s current job position
sourcePage the source page of extracted personal data
lastId ID of the last collected email from the previous response

Email verifier

Check if the provided email addresses are valid or invalid for free. API endpoint will return the email verification results. 

If we haven’t verified a certain email address before, the results will not be returned to you. In this case, the API will return a “not_verified” identifier and you will not be charged credits for this email. You should use the Add Emails for Verification method to push this email address for verification, after which you will be able to get the email verification results using this endpoint.

Request

email verifier

Input Parameters

emails the email addresses you need to verify

Code examples

email verifier

email verifier

Response

Snov.io API

This method will return data for each requested email address. The response consists of an email verification status and verification results.

Output Parameters

status the Email verification status, includes identifier and description
identifier can include such values as “complete“, “in_progress“, or “not_verified“;

if the identifier is “not_verified“, “data” will be empty

description a text description of the verification status
data includes the further verification results – “email“, “isValidFormat“, “isWebmail“, “isGibberish
 email the email address that has been verified
isValidFormat is “true” if the format of email is correct, i.e. it contains valid symbols in the correct order
isDisposable is “true” if we find that this email address is from a disposable email service
isWebmail is “true” if this email address is from a webmail
isGibberish is “true” if this email address has been automatically generated
smtpStatus can return “valid“, “not_valid” or “unknown“; if the value is “unknown“, we can’t provide an SMTP status for this email address

Add emails for verification

If you haven’t verified a certain email address before, you should do it using this API method. It costs 0.5 credit per email address. After performing this action, you can receive the verification results using the Email Verifier method. 

Request

add emails

Input Parameters

emails a list of email addresses you need to add to the verification queue; each request can include up to 10 emails

Code examples

api

add emails

Response

Snov.io API

If an email address is successfully added to the queue, the method returns “sent”:true.

Email finder

This API method finds email addresses using the person’s first name, last name, and a domain name. It costs 1 credit per request. 

We provide the results only if we have this email address in our database. To speed up the process, you can use the Add Names To Find Emails method to push this email address for search. After that, try the Email Finder method again.

Request

email finder

Input Parameters

firstName the email address owner’s first name
lastName the email address owner’s last name
domain the domain name of the company that is used in the email address

Code examples

email finder

email finder

Response

Snov.io API

Output Parameters

status use the values in this object to detect the status of the process
identifier can include the values such as “complete“, “in_progress“, or “not_found“; if the identifier is “not_found“,  the response will include an empty array of emails
description a text description of the email finding status
data includes the search result
firstName the email address owner’s first name
lastName the email address owner’s last name
emails the array of email addresses with their statuses; value “emailStatus” can include: “valid” or “unknown

Add names to find emails

If Snov.io does not have the emails you are looking for in its database and cannot provide these email addresses via the Email Finder, you can push the request for email search using this method. It will cost you 1 credit per request. If an email is found, you can collect it by using the free Email Finder request again.

Request

add names

Input parameters

firstName the email address owner’s first name
lastName the email address owner’s last name
domain the domain name of the company that is used in the email address

Code examples

api

add names

Response

Snov.io API

If the email request was successfully added to the queue, the method returns “sent”:true.

Get profile with email

Enter an email address and get all the profile information connected to the provided email address owner from the database. We charge 1 credit per request. If there is no information about the email owner in our database, you will not be charged for the request.

Request

get profile

Input Parameters

email the email address of the person you want to find additional information on

Code examples

get profile

get profile

Response

Output Parameters

id a unique profile identifier
source the source of the received personal data
name the email address owner’s full name
firstName the person’s first name
lastName the person’s last name
logo the person’s profile photo
industry the person’s industry as indicated in the source
country the person’s country as indicated in the source
locality the person’s locality as indicated in the source
social links to the person’s social profiles
currentJobs an array with information about the person’s current job position
previousJobs an array with information about the person’s previous job position(s)
lastUpdateDate the date of the last profile update in the database

Add prospect to list

Add prospect to a specific list. This method will help automate adding prospects to lists used for active email drip campaigns. This way, after a prospect is added to a chosen list, an email drip campaign will start for them automatically. This method is free, so you don’t need credits to use it.

Request

Add Prospect to List

Input Parameters

email (Required) the prospect’s email address
fullName the prospect’s full name
firstName the prospect’s first name
lastName the prospect’s last name
country the prospect’s country; the country names are defined here (please, only use countries from this list)
locality the prospect’s locality
position the prospect’s job title
companyName the name of the prospect’s company
companySite the prospect’s company website (please, use the http://example.com format)
updateContact updates an existing prospect; can include “true“, or “false“;

if “true” and a prospect with this email address already exists in one of the lists, the system will update the existing profile; if “false“, the system will not update the existing profile

customFields[phone number] you can add your own custom fields; specify the name of the custom field in [brackets]
socialLinks[linkedIn]  a link to the prospect’s social media profile; specify the name of the social network in [brackets] (LinkedIn, Facebook, or Twitter)
listId (Required) the identifier of the list the prospect belongs to

Code examples

api

Add Prospect to List

Response

Snov.io API

Output Parameters

success is “true” if the prospect was successfully added to the list
id added prospect’s identifier
added is “true” if the prospect was added to the list
updated is “true” if the existing prospect’s data has been updated
errors there’s been an error in adding the prospect to the list

Find prospect by ID

Find prospects from your lists by their prospect id. If you know the id of a particular prospect, you can get the full information on the prospect, including the lists and campaigns they’ve been added to. This method is free

Request

Find Prospect by ID

Input Parameters

id (Required) the prospect’s id; you can see it in the response when you add a prospect via Add Prospect to List API method or in the URL when you view prospect’s page (see an example)

Code examples

Find Prospect by ID

Find Prospect by ID

Response

Snov.io API

Output Parameters

success is “true” if the prospect was found
id unique profile identifier
name prospect’s full name
firstName prospect’s first name
lastName prospect’s last name
industry industry as indicated in the prospect’s profile
locality
prospect’s locality
country prospect’s country
social links to prospect’s social profiles
currentJobs array with information about the prospect’s current job title
previousJobs array with information about the prospect’s previous job titles
lastUpdateDate date of last profile update
lists lists that the prospect has been added to
campaigns list of campaigns this prospect has been added to as a recipient; includes status, number of sent messages, opens and replies

Find prospect by email

Find prospect from your lists by email address. When you search by email, you receive a list of all prospects tied to this email address. Every element of the list contains full information on the prospect, including the lists and campaigns they’ve been added to. This method is free.

Request

Find Prospect by Email

Input Parameters

email (Required) the prospect’s email address

Code examples

Find Prospect by Email

Find Prospect by Email

Response

Snov.io API

Output Parameters

success is “true” if the prospect was found
id unique profile identifier
name prospect’s full name
firstName prospect’s first name
lastName prospect’s last name
industry industry as indicated in the prospect’s profile
locality
prospect’s locality
country prospect’s country
social links to prospect’s social profiles
currentJobs array with information about the prospect’s current job title
previousJobs array with information about the prospect’s previous job titles
lastUpdateDate date of last profile update
lists lists that the prospect has been added to
campaigns list of campaigns this prospect has been added to as a recipient; includes status, number of sent messages, opens and replies

Change recipient’s status

Change the status of a recipient in a specific campaign. We do not charge credits for this. 

Request

Change recipient status

Input Parameters

email (Required) the prospect’s email address
campaign_id (Required) the campaign’s id; you can find it in the URL when you view campaign info (show an example)
status (Required) new status for the recipient; can be Active, Paused, Finished, Unsubscribed, Auto-replied, Replied, Replied from another email; you cannot change the recipients’ status if their status is Finished or Moved

Code examples

Change recipient status

Change recipient status

Response

API methods

Output Parameters

Method returns “success: true” if the prospect’s status has been successfully changed. If any error occurs, the method will return “success: false” and the error description.

Add URL to search for prospect

Find a prospect by social URL. To get the results, use the Get prospect with URL method. We charge 1 credit per request.

Request

api

Input Parameters

url the link to the prospect’s social media profile (LinkedIn or Twitter) specified in [brackets]

Code examples

api

api
Response

Response

Output Parameters

success is “true” if the prospect was successfully added to the findlist
message an error occured while adding the prospect to the list

Get prospect with URL

Insert the prospect’s social URL and we will return the full information on the prospect with the found email addresses. You should previously use the Add URL to search for prospect method. Otherwise, the result will not be shown. This method is free.

Request

api

Input Parameters

url the link to the prospect’s social media profile (LinkedIn or Twitter) specified in [brackets]

Code examples

api

api
Response

api
Output Parameters

success is “true” if the prospect was found
id unique profile identifier
name prospect’s full name
firstName prospect’s first name
lastName prospect’s last name
industry industry as indicated in the prospect’s profile
country prospect’s country
locality prospect’s locality
skills prospect’s skills
social links to prospect’s social profiles
currentJobs array with information about the prospect’s current job title
previousJobs array with information about the prospect’s previous job titles
lastUpdateDate date of last profile update
emails
prospect’s email with actual status

Find prospect’s custom fields

Get all custom fields created in your Snov.io account including the fields’ name, whether the field is optional or required, and the field’s data type. This method is free.

Request

api

Input Parameters

api

Code examples

Методи API

Методи API

Response

api

Output Parameters

key the field’s key in the customFields array
label the field’s name
required is “true” if the custom field is required
type the custom field’s data type (string, number, or date)

See user lists

This API method returns all lists created in your Snov.io account. You can get lists that can be used for an email drip campaign. We do not charge credits for this.  

Request

api

Input Parameters

api

Code examples

Методи API

Методи API

Response

api

Output Parameters

id user’s list unique identifier
name list name
contacts the number of prospects in the list
isDeleted list’s status: is “true” if the list has been deleted
vreationDate the date and time of list creation (includes date, time, and time zone info)
deleteDate
if the list has been deleted, contains the date and time of list deletion (includes date, time, and time zone info)

Check user balance

Check your credit balance for free

Request

api

Input Parameters

api

Code examples

Методи API

Методи API

Response

api

Output Parameters

balance
user’s current balance in credits

View prospects in list

This method returns all the data on prospects in a specific list, including prospect’s email addresses and their status. We do not charge credits for this. 

Request

Request

Input Parameters

listId (Required)
the list’s unique identifier
page you can choose on which page of the list you would like to begin your search; this field is optional
perPage you can choose on which page of the list you would like to end your search; this field is optional; the maximum value is 100

Code examples

Методи API

Методи API

Response

Note that the prospect results are displayed in reverse order from last to first.

api

Output Parameters

list an array with information about the list and the prospects in it
name the name of the list
contacts the number of prospects in the list
creation_date the date of list creation (includes date, time, and time zone info)
emailsCount the number of emails in the list
prospects list of prospects in the list
id a prospect’s unique identifier
name a prospect’s full name
emails a list of emails belonging to the prospect

See list of completed prospects

This method returns prospects for whom the email campaign has been completed. You will not be charged credits for this.

Request

new api

Input Parameters

campaignId

(Required)

campaign id to get the prospects list

Code examples

new api

api

Response

api

Output Parameters

id
special identifier
prospectId prospect identifier
userName prospect’s full name
userEmail prospect’s email
campaign campaign name

See campaign replies

Get the campaign replies with all the information such as prospect’s name, ID, campaign, etc. This method is free.

Request

api

Input Parameters

campaignId

(Required)

campaign id to get replies from it

Code examples

api

api

Response

api

Output Parameters

campaignId
campaign id
campaign campaign name
prospectName prospect’s full name
emailSubject email subject
emailBody email content

Get info about campaign replies

This method shows the information about the opened emails in the campaign. We do not charge for it.

Request

api

Input Parameters 

campaignId

(Required)

campaign ID to get replies from it

Code examples

api

api

Response

api

Output Parameters

campaignId
campaign id
campaign campaign name
prospectName prospect’s full name
emailSubject email subject
visitedAt
open time

Check link clicks

Get the overall number of link clicks in the campaign for free.

Request

api

Input Parameters 

campaignId

(Required)

campaign id to get replies from it

Code examples

api

api

Response

api

Output Parameters

campaignId
campaign id
campaign
campaign name
prospectName prospect’s full name
prospectEmail prospect’s email
emailSubject email subject
emailBody
email content
visitedAt open time

View sent emails

Get the information about sent emails in the campaign. We do not charge for this.

Request

Input Parameters

campaignId

(Required)

unique identifier of the campaign for which you want to see sent emails

Code examples

Response

Output Parameters

sentDate
the exact time that the email was sent
userName
full name of the prospect that the email was sent to
userEmail prospect’s email address
campaign campaign name

View all campaigns

Get the list of all user campaigns. This method is free.

Request

Методи API

Input Parameters

api

Code examples

api

api

Response

api

Output Parameters

id
campaign id
campaign
campaign name

Find out more on our API page.

Was this helpful?
5 1