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
POSThttps://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
GEThttps://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
POSThttps://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
POSThttps://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
POSThttps://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
POSThttps://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
POSThttps://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
POSThttps://api.snov.io/v1/get-profile-by-email
Input parameters
email
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
POSThttps://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
or
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
POSThttps://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.

GETGet campaign analytics

Free

This method shows campaign statistics based on the applied filters.

Request
GEThttps://api.snov.io/v2/statistics/campaign-analytics
Input parameters
campaign_id
Campaign ID. You can find it in the URL when you view the campaign info (example). If you leave this field empty, you’ll get data for all active campaigns within the specified time period.

To get data for multiple campaigns, separate IDs with commas.
sender_email
Email sender account ID. You can find it in the URL when viewing or editing the email account info (example). To see analytics for multiple email accounts, separate IDs with commas.

Alternatively, leave this parameter empty if you don’t want to apply an email account filter.
sender_linkedin
LinkedIn sender account ID. You can find it in the URL when viewing or editing the LinkedIn account info. To see analytics for multiple accounts, separate IDs with commas.

Leave this parameter empty if you don’t want to apply a LinkedIn account filter.
campaign_owner
To view campaign data for a specific team member, enter their email address. To filter by multiple campaign owners, list the email addresses separated by commas (no spaces).

Example: example1@gmail.com,example2@gmail.com

Please note that to use this filter, your account must have the ‘View team records’ permission enabled, and you need to be on a Pro plan or higher.
date_from
The start date of the period for which you want to receive statistics. Format: yyyy-mm-dd. Leave empty to receive statistics for all time.
date_to
The end date of the period for which you want to receive statistics. Format: yyyy-mm-dd. Leave empty to receive statistics for all time.
Code examples
<?php
function getCampaignAnalytics()
{
   $token = getAccessToken();
   $campaignIds = [1, 2];
   $senderEmailIds = [21, 22];
   $senderLinkedInIds = [31, 32, 33];
   $ownerEmails = ['owner1@email.loc', 'owner2@email.loc'];
   $params = [
       'access_token' => $token,
       'campaign_id' => implode(',', $campaignIds),
       'sender_email' => implode(',', $senderEmailIds),
       'sender_linkedin' => implode(',', $senderLinkedInIds),
       'campaign_owner' => implode(',', $ownerEmails),
       'date_from' => '2024-06-15',
       'date_to' => '2024-09-15',
   ];
   $params = http_build_query($params);
   $options = [
       CURLOPT_URL => 'https://api.snov.io/v2/statistics/campaign-analytics?' . $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_campaign_analytics():
   token = get_access_token()
   campaign_ids = [1, 2]
   sender_email_ids = [21, 22]
   sender_linkedin_ids = [31, 32, 33]
   owner_emails = ['owner1@email.loc', 'owner2@email.loc']
   params = {
       'access_token': token,
       'campaign_id': ','.join(map(str, campaign_ids)),
       'sender_email': ','.join(map(str, sender_email_ids)),
       'sender_linkedin': ','.join(map(str, sender_linkedin_ids)),
       'campaign_owner': ','.join(owner_emails),
       'date_from': '2024-06-15',
       'date_to': '2024-09-15',
   }
   res = requests.get('https://api.snov.io/v2/statistics/campaign-analytics', params=params)
   return json.loads(res.text)
Response example
{
    "total_contacted": 255,
    "emails_sent": 446,
    "first_emails": 299,
    "first_emails_rate": "67%",
    "follow_ups": 147,
    "follow_ups_rate": "33%",
    "delivered": 363,
    "delivered_rate": "81%",
    "bounced": 83,
    "bounced_rate": "19%",
    "contacted_by_email": 233,
    "email_opens": 130,
    "email_opens_rate": "56%",
    "link_clicks": 100,
    "link_clicks_rate": "43%",
    "email_replies": 29,
    "email_replies_rate": "12%",
    "unsubscribed": 4,
    "unsubscribed_rate": "2%",
    "auto_replied": 13,
    "auto_replied_rate": "6%",
    "contacted_by_linkedin": 23,
    "linkedin_total_replies": 15,
    "linkedin_total_replies_rate": "65%",
    "connection_request_replies": 8,
    "connection_request_replies_rate": "53%",
    "message_replies": 7,
    "message_replies_rate": "47%",
    "connection_requests": 19,
    "accepted_requests": 11,
    "accepted_requests_rate": "58%",
    "failed_connection_requests": 4,
    "messages_sent": 6,
    "linkedin_views": 11,
    "linkedin_likes": 1,
    "linkedin_follows": 3
}
Output parameters
total_contacted
Total number of recipients that were contacted by email or LinkedIn (connection request, message or InMail).
emails_sent
Total number of emails sent via campaigns.

Note that this does not include emails sent outside of campaigns.
first_emails
Number of first emails in a campaign sequence that were sent within the indicated time period.
first_emails_rate
Percentage of first emails out of the total emails sent.
follow_ups
Number of follow-up emails in a campaign sequence that were sent within the indicated time period.
follow_ups_rate
Percentage of follow-up emails out of the total emails sent.
delivered
Number of sent emails that didn’t bounce.
delivered_rate
Percentage of emails that didn’t bounce out of total emails sent.
bounced
Number of emails that bounced.
bounced_rate
Percentage of emails that bounced out of total emails sent.
contacted_by_email
Number of recipients that received at least one email that didn’t bounce.
email_opens
Number of recipients who opened your email at least once.
email_opens_rate
Percentage of recipients who opened your email at least once out of all recipients contacted.
link_clicks
Number of recipients who clicked on at least one link in your campaigns.
link_clicks_rate
Percentage of recipients who clicked on at least one link in campaigns out of all recipients contacted.
email_replies
Number of recipients who replied at least once.
email_replies_rate
Percentage of recipients who replied at least once out of all recipients contacted.
unsubscribed
Number of recipients who clicked the Unsubscribe link in your campaigns, opting out of receiving further emails.
unsubscribed_rate
Percentage of recipients who clicked the Unsubscribe link in your campaigns out of all recipients contacted.
auto_replied
Number of recipients who auto-replied to your campaign emails.
auto_replied_rate
Percentage of recipients who auto-replied out of all recipients contacted.
contacted_by_linkedin
Number of recipients to whom you sent at least one message or connection request on LinkedIn.
linkedin_total_replies
Number of recipients who replied at least once to any of the messages sent on LinkedIn (LinkedIn messages, connection request messages and InMail).
linkedin_total_replies_rate
Percentage of recipients who replied at least once to any of the messages sent on LinkedIn (LinkedIn messages, connection request messages and InMail).
connection_request_replies
Number of recipients who replied to a connection request message.
connection_request_replies_rate
Percentage of recipients who replied to a connection request message out of all recipients contacted.
message_replies
Number of recipients who replied to a regular LinkedIn message.
message_replies_rate
Percentage of recipients who replied to a regular LinkedIn message out of all recipients contacted.
connection_requests
Number of connection requests sent to prospects via Snov.io campaigns.
accepted_requests
Number of connection requests that were accepted by LinkedIn members.
accepted_requests_rate
Percentage of connection requests that were accepted out of all requests sent.
failed_connection_requests
Number of LinkedIn connection requests that were not sent because:
  • prospect's LinkedIn URL doesn't exist
  • you already sent them a connection request before and it's pending
  • you’re already connected with the prospect
messages_sent
Number of LinkedIn messages sent.
linkedin_views
Number of prospect profiles viewed.
linkedin_likes
Number of prospect posts liked on LinkedIn.
linkedin_follows
Number of prospect profiles followed.

GETView campaign progress

Free

This method returns the campaign progress and status.

Request
GEThttps://api.snov.io/v2/campaigns/[campaign_id]/progress
Input parameters
campaign_id
*Required		Campaign ID. You can find it in the URL when you view the campaign info (example).
Code examples
<?php
function getCampaignProgress()
{
   $token = getAccessToken();
   $campaignId = 1;
   $params = [
       'access_token' => $token,
   ];
   $params = http_build_query($params);
   $options = [
       CURLOPT_URL => "https://api.snov.io/v2/campaigns/$campaignId/progress?" . $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_campaign_progress():
   token = get_access_token()
   campaign_id = 1
   params = {
       'access_token': token,
   }
   res = requests.get(f"https://api.snov.io/v2/campaigns/{campaign_id}/progress", params=params)
   return json.loads(res.text)
Response example
{
    "status":"Active",
    "unfinished":1,
    "progress":"90%"
}
Output parameters
progress
Percentage of recipients who:
  • Reached the end of the sequence
  • Bounced, replied, auto-replied, unsubscribed, were deleted, or moved from the campaign, so the campaign was stopped for them.
unfinished
Number of recipients in the campaign who didn’t reach the end of the sequence or for whom the sequence wasn’t stopped.
status
Campaign status. Learn more

POSTChange recipient’s status

Free

Change the status of a recipient in a specific campaign.

Request
POSThttps://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
GEThttps://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
GEThttps://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
GEThttps://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
GEThttps://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
GEThttps://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
GEThttps://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
POSThttps://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
POSThttps://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
POSThttps://api.snov.io/v1/get-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
<?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
POSThttps://api.snov.io/v1/get-prospects-by-email
Input parameters
email
*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
GEThttps://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
GEThttps://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
POSThttps://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
POSThttps://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
GEThttps://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 objectActionWhen triggered
campaign_email
sentWhen any email is sent to the recipient in any drip campaign
first_sentWhen the first email is sent to the recipient in any drip campaign
openedWhen a recipient opens any email from any drip campaign
campaign_reply
receivedWhen the recipient responds to any email in any of the campaigns
first_receivedWhen 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
GEThttps://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:
ParameterData typeData type
data
arrayCollection of webhook models
id
intWebhook ID
end_point
stringThe actual URL that you provided while adding the webhook and where it will be sent to
event_object
stringThe object the action is performed on
event_action
stringAction on the object
created_at
intWebhook creation date in the Unix Timestamp format
status
stringWebhook status: active, deactivated
meta
objectRelated data
webhooks_count
intTotal number of webhooks in your account (max 50)
user_id
intYour user ID

POSTAdd webhook

This API method allows you to create a webhook subscription and receive event notifications to the specified endpoint URL.
Request
POSThttps://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:
ParameterData typeData type
data
objectWebhook data
id
intWebhook ID
end_point
stringThe actual URL that you provided while adding the webhook and where it will be sent to
event_object
stringThe object the action is performed on
event_action
stringAction on the object
created_at
intWebhook creation date in the Unix Timestamp format
status
stringWebhook status: active, deactivated
meta
objectRelated data
user_id
intYour 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
PUThttps://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:
ParameterData typeData type
data
objectWebhook data
id
intWebhook ID
end_point
stringThe actual URL that you provided while adding the webhook and where it will be sent to
event_object
stringThe object the action is performed on
event_action
stringAction on the object
created_at
intWebhook creation date in the Unix Timestamp format
status
stringWebhook status: active, deactivated
meta
objectRelated data
user_id
intYour 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
DELETEhttps://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:
ParameterData typeData type
success
booleanIndicates if the webhook is removed