Snov.io API methods
You can easily use many of Snov.io’s features through our REST API. Integration with Snov.io API allows you to use Snov.io Email Finder, Snov.io Email Verifier and even Email Drip Campaigns tool.
Please note that the API rate is limited to 60 requests per minute.
Outline:
-
-
- How to authenticate requests
- API methods:
- Email count
- Domain search V.2
- Email verifier
- Add emails for verification
- Email finder
- Add names to find emails
- Get profile with email
- Add prospect to list
- Find prospect by ID
- Find prospect by email
- Change recipient’s status
- Add URL to search for prospect
- Get prospect with URL
- Find prospect’s custom fields
- See user lists
- Check user balance
- View prospects in list
- See list of completed prospects
- See campaign replies
- Get info about campaign replies
- Check link clicks
- View sent emails
- View all campaigns
-
Authentication
To authenticate future requests you need to generate an access token. While making a request, paste this access token in the Authorization field. Here is an example:
Request
Input Parameters
| grant_type | will always be “client_credentials“ |
| client_id | your id is available in the account settings https://app.snov.io/api-setting |
| client_secret | your secret key is available in the account settings https://app.snov.io/api-setting |
Code examples
Response
Output Parameters
| access_token | your new access token |
| token_type | will always be Bearer |
| expires_in | token expiration time (in seconds) |
API methods
Currently, we provide almost a dozen API methods:
Email count
This API method helps you know the number of email addresses from a particular domain in our database. It is absolutely free.
Request
Input Parameters
| domain | the name of the domain for which you’d like to know the number of emails in our database |
Code examples
Response
Output Parameters
| domain | the name of the domain for which you’d like to know the number of emails in our database |
| webmail | is “true” if the domain you’re searching is webmail |
| result | a total number of email addresses found for this domain. We can’t provide results for webmail domains, so the result for webmail will always be 0 |
Domain search V.2
Give us a domain name and we will return all the email addresses on the domain. It costs 1 credit per 10 emails/prospects. Any additional information about the email owner available in the database will be added too. Each response returns up to 100 emails. If it does not return at least one email, you will not be charged for the request.
Request
Input Parameters
| domain | the name of the domain from which you want to find the email addresses. E.g. “snov.io” |
| type | can include different values – “all“, “personal” or “generic“;
a generic email address is a role-based email address, for example – contact@snov.io; a personal email address is the email of the actual person working at the company |
| limit | set the limit to specify the number of email addresses to return;
each response returns up to 100 email addresses |
| lastId | to collect more emails than is set in your Limit input parameter, in your next request indicate the id of the last collected email address from the previous request. This way, previously collected emails will be skipped. Note that lastId is a required parameter. The default value is 0). |
Code examples
Response
Output Parameters
| domain | the domain name for which the API has provided the email addresses |
| webmail | is “true” if the domain you’re searching is webmail |
| result | the number of email addresses we have found for this domain. We can’t provide results for webmail domains, so the result for webmail will always be 0 |
| limit | indicates the maximum number of email addresses to return |
| companyName | the company name used to find the email addresses |
| emails | the array of domain emails retrieved in the search |
| a specific email address received in a search | |
| type | can contain “prospect” or “email” values;
if the returned type is “prospect”, Snov.io has found the additional information about the email owner |
| status | email’s verification status; can be “verified” or “notVerified” |
| firstName | the email owner’s first name |
| lastName | the email owner’s last name |
| position | the email owner’s current job position |
| sourcePage | the source page of extracted personal data |
| lastId | ID of the last collected email from the previous response |
Email verifier
Check if the provided email addresses are valid or invalid for free. API endpoint will return the email verification results.
If we haven’t verified a certain email address before, the results will not be returned to you. In this case, the API will return a “not_verified” identifier and you will not be charged credits for this email. You should use the Add Emails for Verification method to push this email address for verification, after which you will be able to get the email verification results using this endpoint.
Request
Input Parameters
| emails | the email addresses you need to verify |
Code examples
Response
This method will return data for each requested email address. The response consists of an email verification status and verification results.
Output Parameters
| status | the Email verification status, includes identifier and description |
| identifier | can include such values as “complete“, “in_progress“, or “not_verified“;
if the identifier is “not_verified“, “data” will be empty |
| description | a text description of the verification status |
| data | includes the further verification results – “email“, “isValidFormat“, “isWebmail“, “isGibberish“ |
| the email address that has been verified | |
| isValidFormat | is “true” if the format of email is correct, i.e. it contains valid symbols in the correct order |
| isDisposable | is “true” if we find that this email address is from a disposable email service |
| isWebmail | is “true” if this email address is from a webmail |
| isGibberish | is “true” if this email address has been automatically generated |
| smtpStatus | can return “valid“, “not_valid” or “unknown“; if the value is “unknown“, we can’t provide an SMTP status for this email address |
Add emails for verification
If you haven’t verified a certain email address before, you should do it using this API method. It costs 0.5 credit per email address. After performing this action, you can receive the verification results using the Email Verifier method.
Request
Input Parameters
| emails | a list of email addresses you need to add to the verification queue; each request can include up to 10 emails |
Code examples
Response
If an email address is successfully added to the queue, the method returns “sent”:true.
Email finder
This API method finds email addresses using the person’s first name, last name, and a domain name. It costs 1 credit per request.
We provide the results only if we have this email address in our database. To speed up the process, you can use the Add Names To Find Emails method to push this email address for search. After that, try the Email Finder method again.
Request
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
Response
Output Parameters
| status | use the values in this object to detect the status of the process |
| identifier | can include the values such as “complete“, “in_progress“, or “not_found“; if the identifier is “not_found“, the response will include an empty array of emails |
| description | a text description of the email finding status |
| data | includes the search result |
| firstName | the email address owner’s first name |
| lastName | the email address owner’s last name |
| emails | the array of email addresses with their statuses; value “emailStatus” can include: “valid” or “unknown“ |
Add names to find emails
If Snov.io does not have the emails you are looking for in its database and cannot provide these email addresses via the Email Finder, you can push the request for email search using this method. It will cost you 1 credit per request. If an email is found, you can collect it by using the free Email Finder request again.
Request
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
Response
If the email request was successfully added to the queue, the method returns “sent”:true.
Get profile with email
Enter an email address and get all the profile information connected to the provided email address owner from the database. We charge 1 credit per request. If there is no information about the email owner in our database, you will not be charged for the request.
Request
Input Parameters
| the email address of the person you want to find additional information on |
Code examples
Response
Output Parameters
| id | a unique profile identifier |
| source | the source of the received personal data |
| name | the email address owner’s full name |
| firstName | the person’s first name |
| lastName | the person’s last name |
| logo | the person’s profile photo |
| industry | the person’s industry as indicated in the source |
| country | the person’s country as indicated in the source |
| locality | the person’s locality as indicated in the source |
| social | links to the person’s social profiles |
| currentJobs | an array with information about the person’s current job position |
| previousJobs | an array with information about the person’s previous job position(s) |
| lastUpdateDate | the date of the last profile update in the database |
Add prospect to list
Add prospect to a specific list. This method will help automate adding prospects to lists used for active email drip campaigns. This way, after a prospect is added to a chosen list, an email drip campaign will start for them automatically. This method is free, so you don’t need credits to use it.
Request
Input Parameters
| email (Required) | the prospect’s email address |
| fullName | the prospect’s full name |
| firstName | the prospect’s first name |
| lastName | the prospect’s last name |
| country | the prospect’s country; the country names are defined here (please, only use countries from this list) |
| locality | the prospect’s locality |
| position | the prospect’s job title |
| companyName | the name of the prospect’s company |
| companySite | the prospect’s company website (please, use the http://example.com format) |
| updateContact | updates an existing prospect; can include “true“, or “false“;
if “true” and a prospect with this email address already exists in one of the lists, the system will update the existing profile; if “false“, the system will not update the existing profile |
| customFields[phone number] | you can add your own custom fields; specify the name of the custom field in [brackets] |
| socialLinks[linkedIn] | a link to the prospect’s social media profile; specify the name of the social network in [brackets] (LinkedIn, Facebook, or Twitter) |
| listId (Required) | the identifier of the list the prospect belongs to |
Code examples
Response
Output Parameters
| success | is “true” if the prospect was successfully added to the list |
| id | added prospect’s identifier |
| added | is “true” if the prospect was added to the list |
| updated | is “true” if the existing prospect’s data has been updated |
| errors | there’s been an error in adding the prospect to the list |
Find prospect by ID
Find prospects from your lists by their prospect id. If you know the id of a particular prospect, you can get the full information on the prospect, including the lists and campaigns they’ve been added to. This method is free.
Request
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
Response
Output Parameters
| success | is “true” if the prospect was found |
| id | unique profile identifier |
| name | prospect’s full name |
| firstName | prospect’s first name |
| lastName | prospect’s last name |
| industry | industry as indicated in the prospect’s profile |
| locality |
prospect’s locality |
| country | prospect’s country |
| social | links to prospect’s social profiles |
| currentJobs | array with information about the prospect’s current job title |
| previousJobs | array with information about the prospect’s previous job titles |
| lastUpdateDate | date of last profile update |
| lists | lists that the prospect has been added to |
| campaigns | list of campaigns this prospect has been added to as a recipient; includes status, number of sent messages, opens and replies |
Find prospect by email
Find prospect from your lists by email address. When you search by email, you receive a list of all prospects tied to this email address. Every element of the list contains full information on the prospect, including the lists and campaigns they’ve been added to. This method is free.
Request
Input Parameters
| email (Required) | the prospect’s email address |
Code examples
Response
Output Parameters
| success | is “true” if the prospect was found |
| id | unique profile identifier |
| name | prospect’s full name |
| firstName | prospect’s first name |
| lastName | prospect’s last name |
| industry | industry as indicated in the prospect’s profile |
| locality |
prospect’s locality |
| country | prospect’s country |
| social | links to prospect’s social profiles |
| currentJobs | array with information about the prospect’s current job title |
| previousJobs | array with information about the prospect’s previous job titles |
| lastUpdateDate | date of last profile update |
| lists | lists that the prospect has been added to |
| campaigns | list of campaigns this prospect has been added to as a recipient; includes status, number of sent messages, opens and replies |
Change recipient’s status
Change the status of a recipient in a specific campaign. We do not charge credits for this.
Request
Input Parameters
| email (Required) | the prospect’s email address |
| campaign_id (Required) | the campaign’s id; you can find it in the URL when you view campaign info (show an example) |
| status (Required) | new status for the recipient; can be Active, Paused, Finished, Unsubscribed, Auto-replied, Replied, Replied from another email; you cannot change the recipients’ status if their status is Finished or Moved |
Code examples
Response
Output Parameters
Method returns “success: true” if the prospect’s status has been successfully changed. If any error occurs, the method will return “success: false” and the error description.
Add URL to search for prospect
Find a prospect by social URL. To get the results, use the Get prospect with URL method. We charge 1 credit per request.
Request
Input Parameters
| url | the link to the prospect’s social media profile (LinkedIn or Twitter) specified in [brackets] |
Code examples
Response
Output Parameters
| success | is “true” if the prospect was successfully added to the findlist |
| message | an error occured while adding the prospect to the list |
Get prospect with URL
Insert the prospect’s social URL and we will return the full information on the prospect with the found email addresses. You should previously use the Add URL to search for prospect method. Otherwise, the result will not be shown. This method is free.
Request
Input Parameters
| url | the link to the prospect’s social media profile (LinkedIn or Twitter) specified in [brackets] |
Code examples
Response
Output Parameters
| success | is “true” if the prospect was found |
| id | unique profile identifier |
| name | prospect’s full name |
| firstName | prospect’s first name |
| lastName | prospect’s last name |
| industry | industry as indicated in the prospect’s profile |
| country | prospect’s country |
| locality | prospect’s locality |
| skills | prospect’s skills |
| social | links to prospect’s social profiles |
| currentJobs | array with information about the prospect’s current job title |
| previousJobs | array with information about the prospect’s previous job titles |
| lastUpdateDate | date of last profile update |
|
emails
|
prospect’s email with actual status |
Find prospect’s custom fields
Get all custom fields created in your Snov.io account including the fields’ name, whether the field is optional or required, and the field’s data type. This method is free.
Request
Input Parameters
Code examples
Response
Output Parameters
| key | the field’s key in the customFields array |
| label | the field’s name |
| required | is “true” if the custom field is required |
| type | the custom field’s data type (string, number, or date) |
See user lists
This API method returns all lists created in your Snov.io account. You can get lists that can be used for an email drip campaign. We do not charge credits for this.
Request
Input Parameters
Code examples
Response
Output Parameters
| id | user’s list unique identifier |
| name | list name |
| contacts | the number of prospects in the list |
| isDeleted | list’s status: is “true” if the list has been deleted |
| vreationDate | the date and time of list creation (includes date, time, and time zone info) |
|
deleteDate
|
if the list has been deleted, contains the date and time of list deletion (includes date, time, and time zone info) |
Check user balance
Check your credit balance for free.
Request
Input Parameters
Code examples
Response
Output Parameters
|
balance
|
user’s current balance in credits |
View prospects in list
This method returns all the data on prospects in a specific list, including prospect’s email addresses and their status. We do not charge credits for this.
Request
Input Parameters
|
listId (Required)
|
the list’s unique identifier |
| page | you can choose on which page of the list you would like to begin your search; this field is optional |
| perPage | you can choose on which page of the list you would like to end your search; this field is optional; the maximum value is 100 |
Code examples
Response
Note that the prospect results are displayed in reverse order from last to first.
Output Parameters
| list | an array with information about the list and the prospects in it |
| name | the name of the list |
| contacts | the number of prospects in the list |
| creation_date | the date of list creation (includes date, time, and time zone info) |
| emailsCount | the number of emails in the list |
| prospects | list of prospects in the list |
| id | a prospect’s unique identifier |
| name | a prospect’s full name |
| emails | a list of emails belonging to the prospect |
See list of completed prospects
This method returns prospects for whom the email campaign has been completed. You will not be charged credits for this.
Request
Input Parameters
|
campaignId
(Required) |
campaign id to get the prospects list |
Code examples
Response
Output Parameters
|
id
|
special identifier |
| prospectId | prospect identifier |
| userName | prospect’s full name |
| userEmail | prospect’s email |
| campaign | campaign name |
See campaign replies
Get the campaign replies with all the information such as prospect’s name, ID, campaign, etc. This method is free.
Request
Input Parameters
|
campaignId
(Required) |
campaign id to get replies from it |
Code examples
Response
Output Parameters
|
campaignId
|
campaign id |
| campaign | campaign name |
| prospectName | prospect’s full name |
| emailSubject | email subject |
| emailBody | email content |
Get info about campaign replies
This method shows the information about the opened emails in the campaign. We do not charge for it.
Request
Input Parameters
|
campaignId
(Required) |
campaign ID to get replies from it |
Code examples
Response
Output Parameters
|
campaignId
|
campaign id |
| campaign | campaign name |
| prospectName | prospect’s full name |
| emailSubject | email subject |
|
visitedAt
|
open time |
Check link clicks
Get the overall number of link clicks in the campaign for free.
Request
Input Parameters
|
campaignId
(Required) |
campaign id to get replies from it |
Code examples
Response
Output Parameters
|
campaignId
|
campaign id |
|
campaign
|
campaign name |
| prospectName | prospect’s full name |
| prospectEmail | prospect’s email |
| emailSubject | email subject |
|
emailBody
|
email content |
| visitedAt | open time |
View sent emails
Get the information about sent emails in the campaign. We do not charge for this.
Request
Input Parameters
|
campaignId
(Required) |
unique identifier of the campaign for which you want to see sent emails |
Code examples
Response
Output Parameters
|
sentDate
|
the exact time that the email was sent |
|
userName
|
full name of the prospect that the email was sent to |
| userEmail | prospect’s email address |
| campaign | campaign name |
View all campaigns
Get the list of all user campaigns. This method is free.
Request
Input Parameters
Code examples
Response
Output Parameters
|
id
|
campaign id |
|
campaign
|
campaign name |
Find out more on our API page.
5
1
