Snov.io API

Snov.io features can be used through our simple REST API. Integrate with Snov.io API to sync your leads, find emails, manage prospects and more. The API rate is limited to 60 requests per minute.

Snov.io users with a free plan can test the API functionality without having to upgrade by contacting us at help@snov.io.

Authentication

You need to generate an access token to authenticate future requests. When making a request, please specify this access token in the Authorization field.

Authorization: Bearer QSlHffXmCAILIOHNGXToq4LsP2yX64VQhEBZ7Ei4

Here is an example for token generation.

Request

POST	https://api.snov.io/v1/oauth/access_token

Input parameters

grant_type	Will always be client_credentials
client_id	Your id is available in the account settingshttps://app.snov.io/account#/api
client_secret	Your secret key is available in the account settingshttps://app.snov.io/account#/api

Code examples

<?php
function getAccessToken()
{
    $params = [
        'grant_type'    => 'client_credentials',
        'client_id'     => 'c57a0459f6t141659ea75cccb393c5111',
        'client_secret' => '77cbf92b71553e85ce3bfd505214f40b'
    ];

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/oauth/access_token',
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $res['access_token'];

}
?>

def get_access_token():
params = {
    'grant_type':'client_credentials',
    'client_id':'c57a0459f6t141659ea75cccb393c111',
    'client_secret': '77cbf92b71553e85ce3bfd505214f40b'
}

res = requests.post('https://api.snov.io/v1/oauth/access_token', data=params)
resText = res.text.encode('ascii','ignore')

return json.loads(resText)['access_token']

Response example

{

"access_token":"3yUyQZdks0Ej7T2fXzjUWzwlTcO4dWisKkeMpESz",

"token_type":"Bearer",

"expires_in":3600

}

Output parameters

access_token	Your new access token
token_type	Will always be Bearer
expires_in	Token expiration time (in seconds)

API methods

GETDomain search V.2

1 credit per 10 emails/prospects

Enter a domain name and Snov.io will return all the email addresses on the domain.

If there is any additional information about the email owner available in the database, we will add it as well.

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

GET	https://api.snov.io/v2/domain-emails-with-info

Input parameters

domain	The name of the domain from which you want to find the email addresses. For example, "snov.io".
type	It can contain 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 .
positions	Use this parameter to filter prospects by job position, for example, "Software Developer". To filter by multiple positions, input an array of neccessary positions.

Code examples

<?php
function getDomainSearch()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'domain'       => 'octagon.com',
        'type'         => 'all',
        'limit'        => 100,
        'lastId'       => 0,
        'positions'    => ['Software Developer','QA']
    ];

    $params = http_build_query($params);
    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v2/domain-emails-with-info?'.$params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $res;

}
?>

def get_domain_search():
token = get_access_token()
params = {
  'access_token': token,
  'domain': 'octagon.com',
  'type': 'all',
  'limit': 100,
  'lastId': 0,
  'positions[]': ['Software Developer','QA']
}

res = requests.get('https://api.snov.io/v2/domain-emails-with-info', params=params)

return json.loads(res.text)

Response example

{
  "success": true,
  "domain": "octagon.com",
  "webmail": false,
  "result": 84,
  "lastId": 1823487525,
  "limit": 100,
  "companyName": "Octagon",
  "emails": [
      {
      "email": "ben.gillespie@octagon.com",
      "firstName": "Ben",
      "lastName": "Gillespie",
      "position": "Senior Account Executive",
      "sourcePage": "https://www.linkedin.com/pub/ben-gillespie/7/73/809",
      "companyName": "Octagon",
      "type": "prospect",
      "status": "verified"
      }
    ]
}

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	Specifies 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 retrieved in the search.
type	Can contain prospect or email values. If the returned type is prospect , Snov.io found additional information about the email owner.
status	Email`s verification status. Email`s 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 retrieved personal data.
lastId	ID of the last collected email from the previous response.

POSTEmail count

Free

With this API method, you can find out the number of email addresses from a certain domain in our database. It`s completely free, so you don`t need credits to use it!

Request

POST	https://api.snov.io/v1/get-domain-emails-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

<?php
function getEmailCount()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'domain'       => 'octagon.com',
    ];

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/get-domain-emails-count',
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $res;

}
?>

def get_email_count():
token = get_access_token()
params = {'access_token':token,
        'domain':'octagon.com'

}

res = requests.post('https://api.snov.io/v1/get-domain-emails-count', data=params)

return json.loads(res.text)

Response example

{

"success":true,

"domain":"octagon.com",

"webmail":false,

"result":1369

}

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 we have found for this domain. We can`t provide results for webmail domains, so the result for webmail will always be 0 .

POSTEmail Finder

Free

This API method finds email addresses using the person`s first and last name, and a domain name. If we don`t have this email address in our database, we won`t be able to provide the results to you right away. 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.

Limits: If you send too many requests in an hour you may see the following error message: "There are too many prospects processing. Please try later"
Hourly search limit depends on your plan:

Starter - 200 requests/hour
Pro 5K - 400 requests/hour
Pro 20K - 600 requests/hour
Pro 50K - 800 requests/hour
Pro 100K - 1000 requests/hour

Request

POST	https://api.snov.io/v1/get-emails-from-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

<?php
function getEmailFinder()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'domain'       => 'octagon.com',
        'firstName'    => 'gavin',
        'lastName'     => 'vanrooyen'
    ];

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/get-emails-from-names',
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $res;

}
?>

def get_email_finder():
token = get_access_token()
params = {'access_token':token,
          'domain':'octagon.com',
          'firstName': 'gavin',
          'lastName':'vanrooyen'
}

res = requests.post('https://api.snov.io/v1/get-emails-from-names', data=params)

return json.loads(res.text)

Response example

{

"success":true,

"params":{

"firstName":"gavin",

"lastName":"vanrooyen",

"domain":"octagon.com"

"data":{

"firstName":"gavin",

"lastName":"vanrooyen",

"emails":[

{

"email":"Gavin@octagon.com",

"emailStatus":"valid"

}

]

"status":{

"identifier":"complete",

"description":"Emails search is completed"

}

Output parameters

status	Use the values in this object to detect the status of the process.
identifier	Can contain the following values: complete , in_progress , or not_found . If the identifier is not_found , the response will contain an empty array of emails.
description	Here you will see a text description of the email finding status.
data	Contains 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 contain: valid or unknown .

POSTAdd names to find emails

1 credit per request

If Snov.io does not have the emails you are looking for in its database and can't provide these email addresses via the Email Finder, you can try to push the request for email search using this method. If an email is found, you can collect it by using the free Email Finder request again.

Limits: If you send too many requests in an hour you may see the following error message: "There are too many prospects processing. Please try later"
Hourly search limit depends on your plan:

Starter - 200 requests/hour
Pro 5K - 400 requests/hour
Pro 20K - 600 requests/hour
Pro 50K - 800 requests/hour
Pro 100K - 1000 requests/hour

Request

POST	https://api.snov.io/v1/add-names-to-find-emails

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

<?php
function getAddNamesToFindEmails()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'domain'       => 'octagon.com',
        'firstName'    => 'gavin',
        'lastName'     => 'vanrooyen'
    ];


    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/add-names-to-find-emails',
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $res;

}
?>

def add_names_to_find_emails():
token = get_access_token()
params = {'access_token':token,
          'domain':'octagon.com',
          'firstName': 'gavin',
          'lastName':'vanrooyen'
}

res = requests.post('https://api.snov.io/v1/add-names-to-find-emails', data=params)

return json.loads(res.text)

Response example

{

"success":true,

"firstName":"gavin",

"lastName":"vanrooyen",

"domain":"octagon.com",

"userId":666871,

"sent":true

}

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

POSTAdd URL to search for prospect

1 credit per request

Find prospects by social URL. To receive the results, use the Get prospect with URL method.

Request

POST	https://api.snov.io/v1/add-url-for-search

Input parameters

url	A link to the prospect’s social media profile. Specify the name of the social network in the [brackets] (LinkedIn or X).

Code examples

<?php
function addUrlForSearch()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'url'          => 'https://www.linkedin.com/in/johndoe/&social'
    ];


    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/add-url-for-search',
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $res;

}
?>

def add_url_for_search():
token = get_access_token()
params = {'access_token':token,
          'url':'https://www.linkedin.com/in/elie-ohayon-aaab7341'
}

res = requests.post('https://api.snov.io/v1/add-url-for-search', data=params)

return json.loads(res.text)

Response example

{
  "success": true
}

Output parameters

success	Is true if the prospect was successfully added to findlist.
message	There’s been an error in adding the prospect to the list.

POSTGet prospect with URL

Free

Provide the prospect's social URL and Snov.io 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.

Request

POST	https://api.snov.io/v1/get-emails-from-url

Input parameters

url	A link to the prospect’s social media profile. Specify the name of the social network in the [brackets] (LinkedIn or X).

Code examples

<?php
function getEmailsFromUrl()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'url'          => 'https://www.linkedin.com/in/john-doe-123456/'
    ];


    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/get-emails-from-url',
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $res;

}
?>

def get_emails_from_url():
token = get_access_token()
params = {'access_token':token,
          'url':'https://www.linkedin.com/in/elie-ohayon-aaab7341'
}

res = requests.post('https://api.snov.io/v1/get-emails-from-url', data=params)

return json.loads(res.text)

Response example

{
  "success": true,
  "data": [
    {
      "id": "xusD3-T_K5IktGoaa8Jc8A==",
      "name": "Gavin Vanrooyen",
      "firstName": "John",
      "lastName": "Doe",
      "sourcePage": "https://www.linkedin.com/in/john-doe-123456/",
      "source": "linkedIn",
      "industry": "Entertainment",
      "country": "United States",
      "locality": "Greater Atlanta Area",
      "lastUpdateDate": {
        "date": "2019-09-11 12:37:58.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "currentJob": [
        {
          "companyName": "Octagon",
          "position": "Senior Brand Director",
          "socialLink": "https:\/\/www.linkedin.com\/company\/659333",
          "site": "http:\/\/octagon.com",
          "locality": "United States",
          "state": null,
          "city": null,
          "street": null,
          "street2": null,
          "postal": null,
          "founded": null,
          "startDate": "2018-07-31",
          "endDate": null,
          "size": "1-10",
          "industry": "Entertainment",
          "companyType": "Public Company",
          "country": "United States"
        }
      ],
      "previousJob": [
        {
          "companyName": "UPS",
          "position": "Manager, Sponsorships and Events",
          "socialLink": "https:\/\/www.linkedin.com\/company\/1523574",
          "site": "http:\/\/www.ups.com\/",
          "locality": "United States",
          "state": "GA",
          "city": "Atlanta",
          "street": "55 Glenlake Parkway, NE",
          "street2": null,
          "postal": "30328",
          "founded": "1907",
          "startDate": null,
          "endDate": null,
          "size": "10001+",
          "industry": "Logistics and Supply Chain",
          "companyType": "Public Company",
          "country": "United States"
        }
      ],
        "social": [],
        "emails": [
            {
                "email": "johndoe@octagon.com",
                "status": "valid"
            }
        ]
    }
  ]
}

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 contains information about the prospect’s current job title
previousJobs	Array contains information about the prospect’s previous job titles
lastUpdateDate	Date of last profile update
emails	Prospect's email with actual status

POSTGet profile with email

1 credit per request

Provide an email address and Snov.io will return all the profile information connected to the provided email address owner from the database.

If we find no information about the email owner in our database, you will not be charged for the request.

Request

POST	https://api.snov.io/v1/get-profile-by-email

Input parameters

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

Code examples

<?php
function getProfileByEmail()
{
    $token = getAccessToken();

    $params = [
        'access_token'    => $token,
        'email'           => 'gavin.vanrooyen@octagon.com'
    ];

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/get-profile-by-email',
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);
    
    return $res;

}
?>

def get_profile_by_email():
token = get_access_token()
params = {'access_token':token,
        'email':'gavin.vanrooyen@octagon.com'
}

res = requests.post('https://api.snov.io/v1/get-profile-by-email', data=params)

return json.loads(res.text)

Response example

{
"success": true,
"id": 301592,
"source": "linkedIn",
"name": "Lizi Hamer",
"firstName": "Lizi",
"lastName": "Hamer",
"logo": "https://app.snov.io/img/peoples/010fcf23c70dfa68d880545ec89a9215.jpg",
"industry": null,
"country": "Singapore",
"locality": "Singapore",
"social": [
    {
        "link": "https://www.linkedin.com/in/lizihamer/",
        "type": "linkedIn"
    },
    {
        "link": "https://twitter.com/LiziHamer",
        "type": "twitter"
    }
],
"currentJobs": [
    {
        "companyName": "Octagon",
        "position": "Regional Creative Director",
        "socialLink": "https://www.linkedin.com/company/165282",
        "site": "www.octagon.com",
        "locality": "Greater New York City Area",
        "state": "Connecticut",
        "city": "Stamford",
        "street": "290 Harbor Dr",
        "street2": "2nd Floor",
        "postal": "06902",
        "founded": "1983",
        "startDate": "2016-01-31",
        "endDate": null,
        "size": "1-10",
        "industry": "Marketing and Advertising",
        "companyType": "Public Company",
        "country": "United States"
    },
    {
        "companyName": "SisuGirls",
        "position": "Co Founder",
        "socialLink": "https://www.linkedin.com/company/3841118",
        "site": "http://www.sisugirls.org",
        "locality": null,
        "state": "SG",
        "city": "Singapore",
        "street": "33-03 Hong Leong Building",
        "street2": null,
        "postal": null,
        "founded": "2014",
        "startDate": "2015-07-31",
        "endDate": null,
        "size": "1-10",
        "industry": "Health, Wellness and Fitness",
        "companyType": null,
        "country": "Singapore"
    }
],
"previousJobs": [
    {
        "companyName": "Fusion Co-innovation Labs",
        "position": "Creative Entrepreneur",
        "socialLink": null,
        "site": null,
        "locality": null,
        "state": null,
        "city": null,
        "street": null,
        "street2": null,
        "postal": null,
        "founded": null,
        "startDate": "2013-05-31",
        "endDate": "2013-10-31",
        "size": null,
        "industry": null,
        "companyType": null,
        "country": null
    },
    {
        "companyName": "Russell Commission",
        "position": "Youth Advisory Board Member",
        "socialLink": null,
        "site": null,
        "locality": null,
        "state": null,
        "city": null,
        "street": null,
        "street2": null,
        "postal": null,
        "founded": null,
        "startDate": "2004-06-30",
        "endDate": "2006-06-30",
        "size": null,
        "industry": null,
        "companyType": null,
        "country": null
    }
],
"lastUpdateDate": "2018-02-07 10:12:28"
}

Output parameters

id	A unique profile identifier.
source	The source of retrieved 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 containing information about the person`s current job position(s).
previousJobs	An array containing information about the person`s previous job position(s).
lastUpdateDate	The date of the last profile update in the database.

POSTEmail Verifier

Free

Check if the provided email addresses are valid and deliverable. 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.

Limits: If you send too many requests in an hour you may see the following error message: "There are too many prospects processing. Please try later"
Hourly search limit depends on your plan:

Starter - 500 emails/hour
Pro 5K - 1000 emails/hour
Pro 20K - 1400 emails/hour
Pro 50K - 2000 emails/hour
Pro 100K - 4000 emails/hour

Request

POST	https://api.snov.io/v1/get-emails-verification-status

Input parameters

emails

The email addresses you need to verify.

Code examples

<?php
function getEmailVerifier()
{
    $token = getAccessToken();
    $emails = ['gavin.vanrooyen@octagon.com', 'lizi.hamer@octagon.com'];

    $emailsQuery = http_build_query(
        [
            'emails' => $emails
        ]
    );
    $params = ['access_token' => $token];

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/get-emails-verification-status?' . $emailsQuery,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $res;

}
?>

def get_email_verifier():
token = get_access_token()
params = {'access_token':token,
}

res = requests.post('https://api.snov.io/v1/get-emails-verification-status?emails[]=gavin.vanrooyen@octagon.com&emails[]=lizi.hamer@octagon.com', data=params)

return json.loads(res.text)

Response example

{

"success":true,

"gavin.vanrooyen@octagon.com":{

"status":{

"identifier":"not_verified",

"description":"Email is not verified, try to send it for verification"

"data":[

]

"lizi.hamer@octagon.com":{

"data":{

"email":"lizi.hamer@octagon.com",

"isValidFormat":true,

"isDisposable":false,

"isWebmail":true,

"isGibberish":false,

"smtpStatus":"valid"

"isCatchall":false

"isGreylist":false

"isBannedError":false

"isConnectionError":false

"status":{

"identifier":"complete",

"description":"Email verification is completed"

}

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

Output parameters

status	The Email verification status. Contains identifier and description.
identifier	Can contain the following values: complete , in_progress , or not_verified . If the identifier is not_verified , data will be empty.
description	Here you will see a text description of the verification status.
data	Contains further verification results - email , isValidFormat , isWebmail , isGibberish , isCatchall , isGreylist , isBannedError , isConnectionError .
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 , greylisted or unknown (aka Unverifiable). You can learn more about email statuses here.
isCatchall	Is true if the email belongs to an email server with a catch-all configuration, meaning it accepts emails even if the recipient is inactive or nonexistent.
isGreylist	Is true if the domain server employs greylisting technology and blocks our attempts to verify the email even when we use bypassing methods.
isBannedError	Is true when we cannot get a response from the server to our connection request.
isConnectionError	Is true when an error occurs on a client's server side during our attempt to establish a connection.

If you get a

greylisted

smtpStatus, it means we are temporarily unable to verify this email and will continue attempts to validate it.
You can resubmit this API request after a short break (usually from 15 minutes to 1 hour) to receive correct results.
Note that we don't charge for emails with

greylisted

status until we finish validating them and receive a definitive SMTP status -

valid

not_valid

POSTAdd emails for verification

1 credit per email address

If you've never verified a certain email address before, you should push it for verification using this API method. After performing this action, you can receive the verification results using the Email Verifier.

Limits: If you send too many requests in an hour you may see the following error message: "There are too many prospects processing. Please try later"
Hourly search limit depends on your plan:

Starter - 500 emails/hour
Pro 5K - 1000 emails/hour
Pro 20K - 1400 emails/hour
Pro 50K - 2000 emails/hour
Pro 100K - 4000 emails/hour

Request

POST	https://api.snov.io/v1/add-emails-to-verification

Input parameters

emails

A list of email addresses you need to add to the verification queue. Each request can contain up to 10 emails.

Code examples

<?php
function addEmailsForVerification()
{
    $token = getAccessToken();
    $emails = ['gavin.vanrooyen@octagon.com', 'lizi.hamer@octagon.com'];

    $emailsQuery = http_build_query(
        [
            'emails' => $emails
        ]
    );
    $params = ['access_token' => $token];

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/add-emails-to-verification?' . $emailsQuery,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $res;

}
?>

def add_emails_for_verification():
token = get_access_token()
params = {'access_token': token
}

res = requests.post('https://api.snov.io/v1/add-emails-to-verification?emails[]=gavin.vanrooyen@octagon.com&emails[]=lizi.hamer@octagon.com', data=params)

return json.loads(res.text)

Response example

{

"success":true,

"gavin.vanrooyen@octagon.com":{

"sent":true

"lizi.hamer@octagon.com":{

"sent":true

}

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

POSTChange recipient’s status

Free

Change the status of a recipient in a specific campaign.

Request

POST	https://api.snov.io/v1/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 the campaign info (show an example).
status *Required	Can contain Active, Paused or Unsubscribed. You can not change the recipients' status if their status is Finished or Moved.

Code examples

<?php
function changeRecipientStatus()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'email'       => 'gavin.vanrooyen@octagon.com',
        'campaign_id'    => '179025',
        'status'     => 'Paused'
    ];


    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/change-recipient-status',
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $res;

}
?>

def change_recipient_status():
token = get_access_token()
params = {'access_token':token,
          'email':'gavin.vanrooyen@octagon.com',
          'campaign_id': '179025',
          'status':'Paused'
}

res = requests.post('https://api.snov.io/v1/change-recipient-status', data=params)

return json.loads(res.text)

Response example

{
  "success": true
}

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 with an error description.

GETSee list of completed prospects

Free

This method returns prospects for whom the campaign has been completed.

Request

GET	https://api.snov.io/v1/prospect-finished

Input parameters

campaignId

*Required

Сampaign's unique identifier to retrieve the prospects list.

Code examples

<?php
function finishedProspects()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'campaignId'   => 1234567
    ];

    $params = http_build_query($params);

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/prospect-finished?'.$params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true,
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);

    curl_close($ch);

    return $res;

}
?>

def user_lists():
token = get_access_token()
params = {'access_token':token,
        'campaignId':1234567
}

res = requests.get('https://api.snov.io/v1/prospect-finished', data=params)

return json.loads(res.text)

Response example

[
    {
        "id": "88c268d404797d1001b4d72806207625",
        "prospectId": "9c2eb5b46bb5873e408684dd577d002354e4f7026f47bf8a592d659bba3d2dd0ff186b90dc7a5",
        "userName": "zach Jones",
        "userEmail": "zach@entselect.us",
        "campaign": "Zipari - Salesforce Developer",
        "hash": "f3967971cbab6e769b5f7e3457d00159"
    }
]

Output parameters

id	Request's unique identifier.
prospectId	Prospect's unique identifier.
userName	Prospect's full name.
userEmail	Prospect's email address.
campaign	Campaign name.

GETSee campaign replies

Free

This method returns the campaign replies with all the information, including the prospect’s name, ID, campaign, etc.

Request

GET	https://api.snov.io/v1/get-emails-replies

Input parameters

campaignId *Required	Unique identifier of the campaign you want to view replies from.
offset	You can collect up to 10,000 replies per each request. If your campaign has more replies, use offset to indicate how many previous replies you want to skip. For example, if your campaign has 20,000 replies and you want to request replies 10,001- 20,000, set the offset as 10,000. If the offset is not specified, you'll get the last 10,000 replies received.

Code examples

<?php
function campaignReplies()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'campaignId'   => 1234567
    ];

    $params = http_build_query($params);

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/get-emails-replies?'.$params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true,
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);

    curl_close($ch);

    return $res;

}
?>

def user_lists():
token = get_access_token()
params = {'access_token':token,
        'campaignId':1234567
}

res = requests.get('https://api.snov.io/v1/get-emails-replies', data=params)

return json.loads(res.text)

Response example

[
    {
        "visitedAt": {
            "date": "2020-07-14 13:10:46.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "campaignId": 1234567,
        "campaign": "My top campaign",
        "prospectId": "7a941739b09f1187532d52a684df545f3a223e432c7f53662264db8d33db80ee5fc19e573416a",
        "prospectFirstName": "John",
        "prospectLastName": "Doe",
        "prospectName": "John Doe",
        "sourcePage": null,
        "source": "copy",
        "locality": null,
        "industry": "Airlines/Aviation",
        "country": null,
        "prospectEmail": "Johndoe@snov.io",
        "hash": "6745f8162ecadbe325693345d1a53976",
        "emailSubject": "\"Special content for you\"",
        "emailBody": "\"<\p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<\/p>\"",
        "skills": "",
        "links": null,
        "customFields": null,
        "id": "f676edc5de58f341dc7bf4e75c0c8580",
        "customField_fdfd": "",
        "customField_рпа": ""
    }
]

Output parameters

campaignId	Campaign's unique identifier.
campaign	Campaign name.
prospectName	Prospect's full name.
emailSubject	Subject line of the email that received a reply.
emailBody	Contents of the email that received a reply.

GETGet info about campaign opens

Free

This method shows the information about the opened emails in the campaign.

Request

GET	https://api.snov.io/v1/get-emails-opened

Input parameters

campaignId *Required	Unique identifier of the campaign for which you want to view information about email opens.
offset	You can collect up to 10,000 opens per each request. If your campaign has more emails opened, use offset to indicate how many previous opens you want to skip. For example, if your campaign has 20,000 opens and you want to request opens 10,001- 20,000, set the offset as 10,000. If the offset is not specified, you'll get the last 10,000 opened emails.

Code examples

<?php
function emailsOpen()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'campaignId'   => 1234567
    ];

    $params = http_build_query($params);

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/get-emails-opened?'.$params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true,
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);

    curl_close($ch);

    return $res;

}
?>

def user_lists():
token = get_access_token()
params = {'access_token':token,
        'campaignId':1234567
}

res = requests.get('https://api.snov.io/v1/get-emails-opened', data=params)

return json.loads(res.text)

Response example

[
    {
        "visitedAt": {
            "date": "2020-01-08 21:48:14.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "campaignId": 1234567
        "campaign": "My top campaign",
        "prospectId": "a9e58c3eecff94e617815a90ca412c4c305045102be1312b41fd0073c9c9f3eee30e090bbc3e3",
        "prospectFirstName": "John",
        "prospectLastName": "Doe",
        "prospectName": "John Doe",
        "sourcePage": null,
        "source": "copy",
        "locality": null,
        "industry": null,
        "country": null,
        "prospectEmail": "Johndoe@snov.io",
        "hash": "20b1aeb0e2949fdf7e58363f84b7aff1",
        "emailSubject": "\"Special content for you\"",
        "emailBody": "\"<\p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<\/p>\"",
	"skills": "",
        "links": null,
        "customFields": null,
        "id": "c2a67a47d59745f548ea7b0213c3a81d",
        "customField_Phone": ""
    }
]

Output parameters

campaignId	Campaign's unique identifier.
campaign	Campaign name.
prospectName	Full name of the prospect that opened an email.
emailSubject	Subject line of the email that was opened.
visitedAt	Exact time the prospect opened the email.

GETCheck link clicks

Free

This method returns information on all campaign recipients that have clicked a link in one of campaign emails.

Request

GET	https://api.snov.io/v1/get-emails-clicked

Input parameters

campaignId *Required	Unique identifier of the campaign you want to view link clicks for.
offset	You can collect up to 10,000 clicks per each request. If your campaign has more clicks, use offset to indicate how many previous clicks you want to skip. For example, if your campaign has 20,000 clicks and you want to request clicks 10,001- 20,000, set the offset as 10,000. If the offset is not specified, you'll get the last 10,000 emails that clicked a link within the campaign.

Code examples

<?php
function emailsClicked()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'campaignId'   => 1234567
    ];

    $params = http_build_query($params);

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/get-emails-clicked?'.$params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true,
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);

    curl_close($ch);

    return $res;

}
?>

def user_lists():
token = get_access_token()
params = {'access_token':token,
        'campaignId':1234567
}

res = requests.get('https://api.snov.io/v1/get-emails-clicked', data=params)

return json.loads(res.text)

Response example

[
    {
        "visitedAt": {
            "date": "2020-01-08 21:48:14.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "campaignId": 1234567
        "campaign": "My top campaign",
        "prospectId": "a9e58c3eecff94e617815a90ca412c4c305045102be1312b41fd0073c9c9f3eee30e090bbc3e3",
        "prospectFirstName": "John",
        "prospectLastName": "Doe",
        "prospectName": "John Doe",
        "sourcePage": null,
        "source": "copy",
        "locality": null,
        "industry": null,
        "country": null,
        "prospectEmail": "Johndoe@snov.io",
        "hash": "20b1aeb0e2949fdf7e58363f84b7aff1",
        "emailSubject": "\"Special content for you\"",
        "emailBody": "\"<\p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<\/p>\"",
	"skills": "",
        "links": null,
        "customFields": null,
        "id": "c2a67a47d59745f548ea7b0213c3a81d",
        "customField_Phone": ""
    }
]

Output parameters

campaignId	Campaign's unique identifier.
campaign	Campaign name.
prospectName	Full name of the prospect that clicked a link from an email in the campaign.
prospectEmail	Prospect's email address.
emailSubject	Subject line of the email that contained a clicked link.
emailBody	Contents of the email.
visitedAt	Exact time the prospect clicked a link in the email.

GETView sent emails

Free

This method shows the information about sent emails in the campaign.

Request

GET	https://api.snov.io/v1/emails-sent

Input parameters

campaignId *Required	Unique identifier of the campaign for which you want to see sent emails.
offset	You can collect up to 10,000 sent emails per each request. If your campaign sent more emails, use offset to indicate how many previous emails you want to skip. For example, if your campaign has 20,000 sent emails and you want to request emails 10,001- 20,000, set the offset as 10,000. If the offset is not specified, you'll get the last 10,000 emails that were sent within the campaign.

Code examples

<?php
function emailsSended()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'campaignId'   => 1234567
    ];

    $params = http_build_query($params);

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/emails-sent?'.$params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true,
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);

    curl_close($ch);

    return $res;

}
?>

def user_lists():
token = get_access_token()
params = {'access_token':token,
        'campaignId':1234567
}

res = requests.get('https://api.snov.io/v1/emails-sent', data=params)

return json.loads(res.text)

Response example

[
    {
        "sentDate": {
            "date": "2020-07-06 06:58:10.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "userName": "John Doe",
        "userEmail": "johndoe@snov.io",
        "campaign": "Test",
        "hash": "be8fd412b793c15ccab9f1a6573d6595",
        "id": "010f091d81860753a19867ba1dd805d1"
    },
    {
        "sentDate": {
            "date": "2020-07-06 06:56:44.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "userName": "Mister Smith",
        "userEmail": "mistersmith@snov.io",
        "campaign": "Test",
        "hash": "55bb20def471e630c539935cb0efcbf8",
        "id": "00e3df8427477a21d64bbe959ff95471"
    }
]

Output parameters

sentDate	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.

GETView all campaigns

Free

This method shows the list of all user campaigns.

Request

GET	https://api.snov.io/v1/get-user-campaigns

Input parameters

There’s no input parameters for this method

Code examples

<?php
function userCampaigns()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token
    ];

    $params = http_build_query($params);

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/get-user-campaigns?'.$params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true,
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);

    curl_close($ch);

    return $res;

}
?>

def user_lists():
token = get_access_token()

headers = {'Authorization': token}

url = 'https://api.snov.io/v1/get-user-campaigns'

response = requests.request('GET', url, headers=headers)

return json.loads(res.text)

Response example

[
    {
        "id": 237945,
        "campaign": "New Campaign",
        "list_id": 8512947,
        "status": "Paused",
        "created_at": 1639469976,
        "updated_at": 1639470026,
        "started_at": 1639470021,
        "hash": "e272be8f9a6894f5b5894fe2ef77095e"
    },
    {
        "id": 237956,
        "campaign": "Test campaign",
        "list_id": 7654321,
        "status": "Draft",
        "created_at": 1638808262,
        "updated_at": 1638808262,
        "started_at": null,
        "hash": "f97fce248b77e9a1ae770b21c7bd783d"
    }
]

Output parameters

id	Unique identifier of the user's campaign.
campaign	Campaign name.
list_id	Unique identifier of the prospect list used in the campaign.
status	Campaign status.
created_at	Campaign creation date and time in the format of Unix Timestamp.
updated_at	Last campaign update date and time in the format of Unix Timestamp.
started_at	Campaign launch date and time in the format of Unix Timestamp.

POSTAdd to Do-not-email List

Free

Using this method you can add an email or a domain to your Do-not-email List. After this email/domain has been added to the list, you won't be able to send emails to it.

Request

POST	https://api.snov.io/v1/do-not-email-list

Input parameters

items	Email or domain you want to add to your Do-not-email List.
listId *Required	The Do-not-email List identifier that emails and domains belong to.

Code examples

<?php
function addToBlackList()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token
    ];

    $data = http_build_query([
      'items' => [
          'gavin.vanrooyen@octagon.com',
          'octagon.com'
      ]
  ]);

    $options = [
        CURLOPT_URL => 'https://api.snov.io/v1/do-not-email-list?'. $data,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $params,
        CURLOPT_FOLLOWLOCATION => true,
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);

    curl_close($ch);
}
?>

def do_not_email_list():
    token = get_access_token()
    params = {
        'access_token':token,
        'items[]':['gavin.vanrooyen@octagon.com','octagon.com']
    }

    res = requests.post('https://api.snov.io/v1/do-not-email-list', data=params)

    return json.loads(res.text)

Response example

[
    {
        "success": true,
        "data": {
            "duplicates": []
        }
    }
]

Output parameters

duplicates

This parameter shows which emails/domains have previously been added to the Do-not-email List.

POSTAdd prospect to list

Free

Add prospect to a specific list. This method will be useful for those who want to automate adding prospects to lists with active email drip campaigns. This way after a prospect is automatically added to a chosen list, an email drip campaign will be started for them automatically.

Request

POST	https://api.snov.io/v1/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.
phones	Array with prospect's phone numbers.
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 contain 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[specialization]	You can add custom values into previously created custom fields. To do this specify the name of the custom field in the [brackets].
socialLinks[linkedIn]	A link to the prospect’s social media profile. Specify the name of the social network in the [brackets] (LinkedIn, Facebook, or X).
listId *Required	The identifier of the list the prospect belongs to.

Code examples

<?php
function addProspectToList()
{
    $token = getAccessToken();

    $params = [
        'access_token'                => $token,
        'email'                       => 'john.doe@example.com',
        'fullName'                    => 'John Doe',
        'firstName'                   => 'John',
        'lastName'                    => 'Doe',
        'phones'                      => ['+18882073333', '+18882074444'],
        'country'                     => 'United States',
        'locality'                    => 'Woodbridge, New Jersey',
        'socialLinks[linkedIn]'       => 'https://www.linkedin.com/in/johndoe/&social',
        'social[twiiter]'             => 'https://twitter.com/johndoe&social',
        'customFields[specialization]'=> 'Software Engineering',
        'position'                    => 'Vice President of Sales',
        'companyName'                 => 'GoldenRule',
        'companySite'                 => 'https://goldenrule.com',
        'updateContact'               => true,
        'listId'                      => '12345',
    ];

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/add-prospect-to-list',
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);
    
    return $res;

}
?>

def add_prospect_to_list():
token = get_access_token()
params = {'access_token':token,
          'email':'john.doe@example.com',
          'fullName': 'John Doe',
          'firstName':'John',
          'lastName':'Doe',
          'phones':['+18882073333', '+18882074444'],
          'country':'United States',
          'locality':'Woodbridge, New Jersey',
          'socialLinks[linkedIn]':'https://www.linkedin.com/in/johndoe/&social',
          'social[twiiter]':'https://twitter.com/johndoe&social',
          'customFields[specialization]':'Software Engineering',
          'position':'Vice President of Sales',
          'companyName':'GoldenRule',
          'companySite':'https://goldenrule.com',
          'updateContact':1,
          'listId':'12345'
}

res = requests.post('https://api.snov.io/v1/add-prospect-to-list', data=params)

return json.loads(res.text)

Response example

{
    "success": true,
    "id": "0Y2QzowWL1rHpIptwaRp0Q==",
    "added": true,
    "updated": false
}

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.

POSTFind prospect by ID

Free

Find prospects from your lists by id. Knowing the id of a specific prospect you can get full information on the prospect, including the lists and campaigns they’ve been added to.

Request

POST	https://api.snov.io/v1/get-prospect-by-id

Input parameters

*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

<?php
function getProspectById()
{
    $token = getAccessToken();

    $params = [
        'access_token'    => $token,
        'id'           => 'xusD3-T_K5IktGoaa8Jc8A=='
    ];

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/get-prospect-by-id',
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);
    
    return $res;

}
?>

def getProspectById():
token = get_access_token()
params = {'access_token':token,
        'id':'xusD3-T_K5IktGoaa8Jc8A=='
}

res = requests.post('https://api.snov.io/v1/get-prospect-by-id', data=params)

return json.loads(res.text)

Response example

{
  "success": true,
  "data": {
    "id": "xusD3-T_K5IktGoaa8Jc8A==",
    "name": "Gavin Vanrooyen",
    "firstName": "Gavin",
    "lastName": "Vanrooyen",
    "industry": "Entertainment",
    "country": "United States",
    "locality": "Greater Atlanta Area",
    "social": [
      {
        "link": "https:\/\/www.linkedin.com\/in\/gavin-vanrooyen-8090738\/",
        "type": "linkedIn"
      }
    ],
    "lastUpdateDate": {
      "date": "2019-09-11 12:37:58.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "currentJob": [
      {
        "companyName": "Octagon",
        "position": "Senior Brand Director",
        "socialLink": "https:\/\/www.linkedin.com\/company\/659312",
        "site": "http:\/\/octagon.com",
        "locality": "United States",
        "state": null,
        "city": null,
        "street": null,
        "street2": null,
        "postal": null,
        "founded": null,
        "startDate": "2018-07-31",
        "endDate": null,
        "size": "1-10",
        "industry": "Entertainment",
        "companyType": "Public Company",
        "country": "United States"
      }
    ],
    "previousJob": [
      {
        "companyName": "UPS",
        "position": "Manager, Sponsorships and Events",
        "socialLink": "https:\/\/www.linkedin.com\/company\/152322",
        "site": "http:\/\/www.ups.com\/",
        "locality": "United States",
        "state": "GA",
        "city": "Atlanta",
        "street": "55 Glenlake Parkway, NE",
        "street2": null,
        "postal": "30328",
        "founded": "1907",
        "startDate": null,
        "endDate": null,
        "size": "10001+",
        "industry": "Logistics and Supply Chain",
        "companyType": "Public Company",
        "country": "United States"
      }
    ],
    "lists": [
      {
        "id": 1250344,
        "name": "People List"
      }
    ],
    "campaigns": []
  }
}

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
social	Links to prospect’s social profiles
currentJobs	Array contains information about the prospect’s current job title
previousJobs	Array contains 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. Contains short statistics such as status, number of sent messages, opens and replies.

POSTFind prospect by email

Free

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.

Request

POST	https://api.snov.io/v1/get-prospects-by-email

Input parameters

*Required

The prospect’s email address.

Code examples

<?php
function getProspectsByEmail()
{
    $token = getAccessToken();

    $params = [
        'access_token'    => $token,
        'email'           => 'gavin.vanrooyen@octagon.com'
    ];

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/get-prospects-by-email',
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);
    
    return $res;

}
?>

def getProspectsByEmail():
token = get_access_token()
params = {'access_token':token,
        'email':'gavin.vanrooyen@octagon.com'
}

res = requests.post('https://api.snov.io/v1/get-prospects-by-email', data=params)

return json.loads(res.text)

Response example

{
  "success": true,
  "data": [
    {
      "id": "xusD3-T_K5IktGoaa8Jc8A==",
      "name": "Gavin Vanrooyen",
      "firstName": "Gavin",
      "lastName": "Vanrooyen",
      "industry": "Entertainment",
      "country": "United States",
      "locality": "Greater Atlanta Area",
      "social": [
        {
          "link": "https:\/\/www.linkedin.com\/in\/gavin-vanrooyen-809073755\/",
          "type": "linkedIn"
        }
      ],
      "lastUpdateDate": {
        "date": "2019-09-11 12:37:58.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "currentJob": [
        {
          "companyName": "Octagon",
          "position": "Senior Brand Director",
          "socialLink": "https:\/\/www.linkedin.com\/company\/659333",
          "site": "http:\/\/octagon.com",
          "locality": "United States",
          "state": null,
          "city": null,
          "street": null,
          "street2": null,
          "postal": null,
          "founded": null,
          "startDate": "2018-07-31",
          "endDate": null,
          "size": "1-10",
          "industry": "Entertainment",
          "companyType": "Public Company",
          "country": "United States"
        }
      ],
      "previousJob": [
        {
          "companyName": "UPS",
          "position": "Manager, Sponsorships and Events",
          "socialLink": "https:\/\/www.linkedin.com\/company\/1523574",
          "site": "http:\/\/www.ups.com\/",
          "locality": "United States",
          "state": "GA",
          "city": "Atlanta",
          "street": "55 Glenlake Parkway, NE",
          "street2": null,
          "postal": "30328",
          "founded": "1907",
          "startDate": null,
          "endDate": null,
          "size": "10001+",
          "industry": "Logistics and Supply Chain",
          "companyType": "Public Company",
          "country": "United States"
        }
      ],
      "lists": [
        {
          "id": 1250344,
          "name": "People List"
        }
      ],
      "campaigns": []
    }
  ]
}

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
social	Links to prospect’s social profiles
currentJobs	Array contains information about the prospect’s current job title
previousJobs	Array contains 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. Contains short statistics such as status, number of sent messages, opens and replies.

GETFind prospect’s custom fields

Free

This method returns a list of all custom fields created by the user, including the fields’ name, whether the field is optional or required, and the field’s data type.

Request

GET	https://api.snov.io/v1/prospect-custom-fields

Input parameters

There’s no input parameters for this method

Code examples

<?php
function customFields()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
    ];

    $params = http_build_query($params);

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/prospect-custom-fields?'.$params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);

    curl_close($ch);

    return $res;

}
?>

def custom_fields():
token = get_access_token()
params = {'access_token':token
}

res = requests.get('https://api.snov.io/v1/prospect-custom-fields', data=params)

return json.loads(res.text)

Response example

  [
    {
        "key": "customFields['company']",
        "label": "company",
        "required": false,
        "type": "string"
    },
    {
        "key": "customFields['Project name']",
        "label": "Project name",
        "required": false,
        "type": "string"
    },
    {
        "key": "customFields['SEO']",
        "label": "SEO",
        "required": false,
        "type": "string"
    }
  ]

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).

GETSee user lists

Free

This method returns all lists created by the user. You can use this method to review lists that can be used for an email drip campaign.

Request

GET	https://api.snov.io/v1/get-user-lists

Input parameters

There’s no input parameters for this method

Code examples

<?php
function getUserLists()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
    ];

    $params = http_build_query($params);

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/get-user-lists?'.$params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);

    curl_close($ch);

    return $res;

}
?>

def user_lists():
token = get_access_token()
params = {'access_token':token
}

res = requests.get('https://api.snov.io/v1/get-user-lists', data=params)

return json.loads(res.text)

Response example

[
    {
        "id": 1818597,
        "name": "FirstSend",
        "contacts": 1,
        "isDeleted": false,
        "creationDate": {
            "date": "2020-04-07 08:25:44.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "deletionDate": null
    },
    {
        "id": 1505383,
        "name": "All prospects",
        "contacts": 10,
        "isDeleted": true,
        "creationDate": {
            "date": "2019-12-17 15:07:30.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "deletionDate": {
            "date": "2020-02-17 14:05:44.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    },
    {
        "id": 1479070,
        "name": "EMAIL",
        "contacts": 13,
        "isDeleted": true,
        "creationDate": {
            "date": "2019-12-06 10:51:01.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "deletionDate": {
            "date": "2020-02-17 14:05:48.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    }
]

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.
creationDate	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).

POSTView prospects in list

Free

This method returns all the data on prospects in a specific list, including prospect’s data like email addresses and their status.

Request

POST	https://api.snov.io/v1/prospect-list

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. Maximum value is 100.

Code examples

<?php
function prospectsInList()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'listId'       => '1234567',
        'page'         => '1',
        'perPage'      => '2'
    ];

    $options = [
        CURLOPT_URL            => ' https://api.snov.io/v1/prospect-list',
        CURLOPT_POSTFIELDS     => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);

    curl_close($ch);

    return $res;

}
?>

def prospect_in_list():
token = get_access_token()
params = {'access_token':token,
        'listId':'1234567',
        'page':'1',
        'perPage':'2'
}

res = requests.post('https://api.snov.io/v1/prospect-list', params=params)

return json.loads(res.text)

Response example

Please note, the prospect results are displayed in reverse order from last to first.

{
    "success": true,
    "list": {
        "name": "Lead LIST",
        "contacts": 3,
        "creationDate": {
            "date": "2020-05-19 17:34:39.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "emailsCount": []
    },
    "prospects": [
        {
            "id": "226db935fc93422496fda5d5209e8cbf77cc77ec685891706028009b86608f7ce5877a3faf",
            "name": "Andrew Garfiled",
            "firstName": "Andrew",
            "lastName": "Garfiled",
            "emails": [
                {
                    "email": "andrewexp@exp.com",
                    "probability": 99,
                    "isVerified": null,
                    "jobStatus": "any",
                    "domainType": "linkedin_email",
                    "isValidFormat": null,
                    "isDisposable": null,
                    "isWebmail": null,
                    "isGibberish": null,
                    "smtpStatus": null
                }
            ]
        },
        {
            "id": "f20d30219b039d1408d837a748a1e2ab843c97e65080f6cf8fa7d948477d9093d87413f05f",
            "name": "John Doe",
            "firstName": "John",
            "lastName": "Doe",
            "emails": [
                {
                    "email": "johndoe@gmail.com",
                    "probability": 99,
                    "isVerified": null,
                    "jobStatus": "any",
                    "domainType": "linkedin_email",
                    "isValidFormat": true,
                    "isDisposable": false,
                    "isWebmail": true,
                    "isGibberish": false,
                    "smtpStatus": 3
                }
            ]
        }
    ]
}

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	A 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.

POSTCreate new prospect list

Free

Use this method to create new prospect lists in your account.

Request

POST	https://api.snov.io/v1/lists

Input parameters

name	The name of the new prospect list.

Code examples

<?php
function createNewList()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
        'name' => 'New list'
    ];

    $options = [
        CURLOPT_URL => 'https://api.snov.io/v1/lists',
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true,
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);

    curl_close($ch);
}
?>

def add_prospect_list():
    token = get_access_token()
    params = {
        'access_token':token,
        'name':'New list'
    }

    res = requests.post('https://api.snov.io/v1/lists', data=params)

    return json.loads(res.text)

Response example

[
    {
        "success": true,
        "data": {
            "id": 1234567
        }
    }
]

Output parameters

id	The ID of the created prospect list.

GETCheck user balance

Free

Use this method to check your credit balance.

Request

GET	https://api.snov.io/v1/get-balance

Input parameters

There’s no input parameters for this method

Code examples

<?php
function getBalance()
{
    $token = getAccessToken();

    $params = [
        'access_token' => $token,
    ];

    $params = http_build_query($params);

    $options = [
        CURLOPT_URL            => 'https://api.snov.io/v1/get-balance?'.$params,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true
    ];

    $ch = curl_init();

    curl_setopt_array($ch, $options);

    $res = json_decode(curl_exec($ch), true);

    curl_close($ch);

    return $res;

}
?>

def get_balance():
token = get_access_token()
headers = {'authorization':token
}

res = requests.get('https://api.snov.io/v1/get-balance', headers=headers)

return json.loads(res.text)

Response example

{
    "success": true,
    "data": {
        "balance": "25000.00",
        "teamwork": false,
        "unique_recipients_used": 0,
        "limit_resets_in": 29,
        "expires_in": 359
    }
}

Output parameters

balance	User’s current balance in credits.
teamwork	Is true if you are currently a team member or leader, false if you are not a part of a team.
recipients_used	Number of unique recipients used this month.
limit_resets_in	Days till the limit reset.
expires_in	Days till the end of subscription.

Webhooks

Description

Webhooks allow you to get notified of events that happened in your Snov.io account.

You can use webhooks to call the endpoint (URL) on your server each time a subscribed event occurs in Snov.io and send real-time data to your application.

Whenever an event occurs, Snov.io sends an HTTP request with a JSON body to the specified URL-endpoint.

You can subscribe to and manage webhooks through a set of API calls.

Currently supported webhook objects and actions are listed below:

Webhook object	Action	When triggered
campaign_email	sent	When any email is sent to the recipient in any drip campaign
	first_sent	When the first email is sent to the recipient in any drip campaign
	opened	When a recipient opens any email from any drip campaign
campaign_reply	received	When the recipient responds to any email in any of the campaigns
campaign_reply	first_received	When the recipient responds to the email for the first time in any of the campaigns

Limits: premium plan users can create up to 50 webhooks.

Retry policy: The webhook is successful if we receive an HTTP status from 200-299 range in response within 3 seconds.

If we get any other HTTP status or a timeout occurs, we make seven retry attempts with increasing intervals up to 38 hours after the event which triggered a webhook:

If all retries are unsuccessful, the webhook becomes deactivated.

1st: immediately after the event
2nd: 20 minutes after the last attempt (20 minutes after the event)
3rd: 40 minutes after the last attempt (1 hour after the event)
4th: 60 minutes after the last attempt (2 hours after the event)
5th: 4 hours after the last attempt (6 hours after the event)
6th: 8 hours after the last attempt (14 hours after the event)
7th: 24 hours after the last attempt (38 hours after the event)

GETList all webhooks

This API method allows you to get a list of webhooks on your account.

Request

GET	https://api.snov.io/v2/webhooks

Request header

Content-Type: application/json

Input parameters

This method has no input parameters.

Response example

{
    "data": [
        {
            "data": {
                "id": 8,
                "end_point": "https://hooks.yourdomain.com/hooks/catch/1237321/awwwcz/",
                "event_object": "campaign_email",
                "event_action": "sent",
                "status": "active",
                "created_at": 1655847444
            }
        },
        {
            "data": {
                "id": 14,
                "end_point": "https://hooks.yourdomain.com/hooks/catch/1237321/abqqqpcz/",
                "event_object": "campaign_email",
                "event_action": "sent",
                "status": "deactivated",
                "created_at": 1655890563
            }
        },
        {
            "data": {
                "id": 17,
                "end_point": "https://hooks.yourdomain.com/hooks/catch/1237321/abwfpcz/",
                "event_object": "campaign_email",
                "event_action": "sent",
                "status": "active",
                "created_at": 1656057947
            }
        }
    ],
    "meta": {
        "webhooks_count": 3,
        "user_id": 1313777
    }
}

Output parameters

The response returns a collection of webhook models. The properties of the model are listed below:

Parameter	Data type	Data type
data	array	Collection of webhook models
id	int	Webhook ID
end_point	string	The actual URL that you provided while adding the webhook and where it will be sent to
event_object	string	The object the action is performed on
event_action	string	Action on the object
created_at	int	Webhook creation date in the Unix Timestamp format
status	string	Webhook status: active, deactivated
meta	object	Related data
webhooks_count	int	Total number of webhooks in your account (max 50)
user_id	int	Your user ID

POSTAdd webhook

This API method allows you to create a webhook subscription and receive event notifications to the specified endpoint URL.

Request

POST	https://api.snov.io/v2/webhooks

Request header

Content-Type: application/json

Input parameters

event_object	the object the action is performed on (list of supported objects)
event_action	the action performed on the object (list of supported actions)
endpoint_url	the URL address where the webhook is sent

Request example

{
  "event_object": "campaign_email",
  "event_action": "sent",
  "endpoint_url": "https://hooks.yourdomain.com/hooks/catch/1237321/abwfpcz/"
}

Response example

{
    "data": {
        "id": 17,
        "end_point": "https://hooks.yourdomain.com/hooks/catch/1237321/abwfpcz/",
        "event_object": "campaign_email",
        "event_action": "sent",
        "created_at": 1656057947,
        "status": "active"
    },
    "meta": {
        "user_id": 1313777
    }
}

Output parameters

The response returns a model of the added webhook. The properties of the model are listed below:

Parameter	Data type	Data type
data	object	Webhook data
id	int	Webhook ID
end_point	string	The actual URL that you provided while adding the webhook and where it will be sent to
event_object	string	The object the action is performed on
event_action	string	Action on the object
created_at	int	Webhook creation date in the Unix Timestamp format
status	string	Webhook status: active, deactivated
meta	object	Related data
user_id	int	Your user ID

PUTChange webhook status

Changes the status of a chosen webhook subscription.

Include the unique “id” value of the chosen webhook at the end of the request URL address.

Use List all webhooks method to get id values of your webhooks.

Request

PUT	https://api.snov.io/v2/webhooks/webhook_id

Request header

Content-Type: application/json

Input parameters

status

active or deactivated

Request example

{
    https://api.snov.io/v2/webhooks/14
    "status": "deactivated"
}

Response example

{
    "data": {
        "id": 14,
        "end_point": "https://hooks.yourdomain.com/hooks/catch/1237321/abqqqpcz/",
        "event_object": "campaign_email",
        "event_action": "sent",
        "created_at": 1655890563,
        "status": "deactivated"
    },
    "meta": {
        "user_id": 1313777
    }
}

Output parameters

The response returns a model of the added webhook. The properties of the model are listed below:

Parameter	Data type	Data type
data	object	Webhook data
id	int	Webhook ID
end_point	string	The actual URL that you provided while adding the webhook and where it will be sent to
event_object	string	The object the action is performed on
event_action	string	Action on the object
created_at	int	Webhook creation date in the Unix Timestamp format
status	string	Webhook status: active, deactivated
meta	object	Related data
user_id	int	Your user ID

DELETEDelete a webhook

Deletes a chosen webhook.

Include the unique “id” value of the chosen webhook at the end of the request URL address.

Use List all webhooks method to get id values of your webhooks.

Request

DELETE

https://api.snov.io/v2/webhooks/webhook_id

Request header

Content-Type: application/json

Request example

{
    https://api.snov.io/v2/webhooks/8
}

Response example

{
    "data": {
        "success": true
    }
}

Output parameters

The response returns a collection of webhook models. The properties of the model are listed below:

Parameter	Data type	Data type
success	boolean	Indicates if the webhook is removed