Snov.io User & Balance API
Reports the account's current credit balance and plan usage for free, letting integrations check remaining credits before running metered search and verification calls.
OpenAPI Specification
openapi: 3.0.3
info:
title: Snov.io API
description: >-
Snov.io sales engagement REST API. Authentication uses the OAuth2
client_credentials grant to exchange an API User ID (client_id) and API
Secret (client_secret) for a one-hour Bearer access token. Email finder,
domain search, and email verification use an asynchronous pattern: a POST
to a `/start` endpoint returns a `task_hash`, then a GET to the matching
`/result` endpoint retrieves the outcome. Most request bodies are
application/x-www-form-urlencoded; a few v2 endpoints accept JSON. The API
is rate limited to 60 requests per minute.
termsOfService: https://snov.io/terms-and-conditions
contact:
name: Snov.io Support
url: https://snov.io/api
version: '1.0'
servers:
- url: https://api.snov.io
description: Snov.io production API
tags:
- name: Authentication
- name: Email Finder
- name: Domain Search
- name: Email Verifier
- name: Enrichment
- name: Prospects
- name: Campaigns
- name: Sender Accounts
- name: Warm-up
- name: User
security:
- OAuth2: []
paths:
/v1/oauth/access_token:
post:
operationId: getAccessToken
tags:
- Authentication
summary: Get an OAuth2 access token
description: >-
Exchanges client_id (API User ID) and client_secret (API Secret) for a
Bearer access token using the client_credentials grant. The token is
valid for 3600 seconds.
security: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- grant_type
- client_id
- client_secret
properties:
grant_type:
type: string
enum:
- client_credentials
client_id:
type: string
client_secret:
type: string
responses:
'200':
description: Access token issued.
content:
application/json:
schema:
$ref: '#/components/schemas/AccessToken'
/v2/emails-by-domain-by-name/start:
post:
operationId: startEmailsByDomainByName
tags:
- Email Finder
summary: Start finding emails by name and domain
description: >-
Starts an asynchronous task that finds verified emails for one or more
prospects given their first name, last name, and company domain. Returns
a task_hash used to retrieve the result. Costs 1 credit per email.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- rows
properties:
rows:
type: array
items:
type: object
required:
- first_name
- last_name
- domain
properties:
first_name:
type: string
last_name:
type: string
domain:
type: string
webhook_url:
type: string
format: uri
responses:
'200':
description: Task started.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
/v2/emails-by-domain-by-name/result:
get:
operationId: getEmailsByDomainByNameResult
tags:
- Email Finder
summary: Get emails-by-name result
parameters:
- $ref: '#/components/parameters/TaskHashQuery'
responses:
'200':
description: Result payload with found emails and statuses.
content:
application/json:
schema:
type: object
additionalProperties: true
/v2/company-domain-by-name/start:
post:
operationId: startCompanyDomainByName
tags:
- Email Finder
summary: Start company domain lookup by name
description: Retrieves a company website domain from a business name. Costs 1 credit per domain found.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- name
properties:
name:
type: string
responses:
'200':
description: Task started.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
/v2/company-domain-by-name/result:
get:
operationId: getCompanyDomainByNameResult
tags:
- Email Finder
summary: Get company domain lookup result
parameters:
- $ref: '#/components/parameters/TaskHashQuery'
responses:
'200':
description: Resolved company domain.
content:
application/json:
schema:
type: object
additionalProperties: true
/v2/domain-search/start:
post:
operationId: startDomainSearch
tags:
- Domain Search
summary: Start a domain search
description: Starts a company info and prospect search by domain. Costs 1 credit per unique request.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- domain
properties:
domain:
type: string
webhook_url:
type: string
format: uri
responses:
'200':
description: Task started.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
/v2/domain-search/result/{task_hash}:
get:
operationId: getDomainSearchResult
tags:
- Domain Search
summary: Get domain search result
parameters:
- $ref: '#/components/parameters/TaskHashPath'
responses:
'200':
description: Company information for the domain.
content:
application/json:
schema:
type: object
additionalProperties: true
/v2/domain-search/prospects/start:
post:
operationId: startDomainProspects
tags:
- Domain Search
summary: Start prospect profile search for a domain
description: >-
Finds prospect profiles for a domain with optional job position filters.
Costs 1 credit per unique request and 1 credit per prospect with email.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- domain
properties:
domain:
type: string
positions:
type: string
description: Comma-separated job positions to filter by.
responses:
'200':
description: Task started.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
/v2/domain-search/prospects/result/{task_hash}:
get:
operationId: getDomainProspectsResult
tags:
- Domain Search
summary: Get domain prospects result
parameters:
- $ref: '#/components/parameters/TaskHashPath'
responses:
'200':
description: Prospect profiles for the domain.
content:
application/json:
schema:
type: object
additionalProperties: true
/v2/domain-search/domain-emails/start:
post:
operationId: startDomainEmails
tags:
- Domain Search
summary: Start domain emails search
description: Searches for unverified email addresses from a company domain. Costs 1 credit per unique request.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- domain
properties:
domain:
type: string
responses:
'200':
description: Task started.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
/v2/domain-search/domain-emails/result/{task_hash}:
get:
operationId: getDomainEmailsResult
tags:
- Domain Search
summary: Get domain emails result
parameters:
- $ref: '#/components/parameters/TaskHashPath'
responses:
'200':
description: Emails found for the domain.
content:
application/json:
schema:
type: object
additionalProperties: true
/v2/domain-search/generic-contacts/start:
post:
operationId: startGenericContacts
tags:
- Domain Search
summary: Start generic contacts search
description: Finds generic company email addresses (orders@, sales@, info@). Costs 1 credit per unique request.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- domain
properties:
domain:
type: string
responses:
'200':
description: Task started.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
/v2/domain-search/generic-contacts/result/{task_hash}:
get:
operationId: getGenericContactsResult
tags:
- Domain Search
summary: Get generic contacts result
parameters:
- $ref: '#/components/parameters/TaskHashPath'
responses:
'200':
description: Generic contacts found for the domain.
content:
application/json:
schema:
type: object
additionalProperties: true
/v1/get-domain-emails-count:
post:
operationId: getDomainEmailsCount
tags:
- Domain Search
summary: Get domain emails count (free)
description: Returns the total count of emails available for a domain without consuming credits.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- domain
properties:
domain:
type: string
responses:
'200':
description: Email count for the domain.
content:
application/json:
schema:
type: object
additionalProperties: true
/v2/email-verification/start:
post:
operationId: startEmailVerification
tags:
- Email Verifier
summary: Start email verification
description: >-
Starts verification for up to ten email addresses at once. Each email is
added as a separate parameter. Supports an optional webhook_url for async
delivery of results.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- emails
properties:
emails:
type: array
maxItems: 10
items:
type: string
format: email
webhook_url:
type: string
format: uri
responses:
'200':
description: Verification task started.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
/v2/email-verification/result:
get:
operationId: getEmailVerificationResult
tags:
- Email Verifier
summary: Get email verification result
parameters:
- $ref: '#/components/parameters/TaskHashQuery'
responses:
'200':
description: Verification results with SMTP and quality signals.
content:
application/json:
schema:
$ref: '#/components/schemas/EmailVerificationResult'
/v1/get-profile-by-email:
post:
operationId: getProfileByEmail
tags:
- Enrichment
summary: Get profile by email
description: Retrieves comprehensive profile data connected to an email address. Costs 1 credit per request (no charge if no data is found).
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
responses:
'200':
description: Profile data for the email.
content:
application/json:
schema:
type: object
additionalProperties: true
/v2/li-profiles-by-urls/start:
post:
operationId: startLiProfilesByUrls
tags:
- Enrichment
summary: Start LinkedIn profile enrichment
description: Extracts complete profile information from LinkedIn member URLs. Costs 1 credit per prospect profile.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- urls
properties:
urls:
type: array
items:
type: string
format: uri
responses:
'200':
description: Task started.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
/v2/li-profiles-by-urls/result:
get:
operationId: getLiProfilesByUrlsResult
tags:
- Enrichment
summary: Get LinkedIn profile enrichment result
parameters:
- $ref: '#/components/parameters/TaskHashQuery'
responses:
'200':
description: Enriched LinkedIn profiles.
content:
application/json:
schema:
type: object
additionalProperties: true
/v1/get-user-lists:
get:
operationId: getUserLists
tags:
- Prospects
summary: List the user's prospect lists
responses:
'200':
description: The user's prospect lists.
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: true
/v1/lists:
post:
operationId: createList
tags:
- Prospects
summary: Create a new prospect list
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- name
properties:
name:
type: string
responses:
'200':
description: The created list.
content:
application/json:
schema:
type: object
additionalProperties: true
/v1/prospect-list:
post:
operationId: getProspectList
tags:
- Prospects
summary: View prospects in a list
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- listId
properties:
listId:
type: integer
page:
type: integer
perPage:
type: integer
responses:
'200':
description: Prospects contained in the list.
content:
application/json:
schema:
type: object
additionalProperties: true
/v1/add-prospect-to-list:
post:
operationId: addProspectToList
tags:
- Prospects
summary: Add a prospect to a list
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- email
- listId
properties:
email:
type: string
format: email
fullName:
type: string
firstName:
type: string
lastName:
type: string
position:
type: string
companyName:
type: string
listId:
type: integer
responses:
'200':
description: The prospect added to the list.
content:
application/json:
schema:
type: object
additionalProperties: true
/v1/get-user-campaigns:
get:
operationId: getUserCampaigns
tags:
- Campaigns
summary: List the user's drip campaigns
responses:
'200':
description: The user's campaigns.
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: true
/v1/get-emails-sent:
post:
operationId: getEmailsSent
tags:
- Campaigns
summary: Get emails sent for a campaign
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CampaignReportRequest'
responses:
'200':
description: Emails sent in the campaign.
content:
application/json:
schema:
type: object
additionalProperties: true
/v1/get-emails-opened:
post:
operationId: getEmailsOpened
tags:
- Campaigns
summary: Get emails opened for a campaign
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CampaignReportRequest'
responses:
'200':
description: Emails opened in the campaign.
content:
application/json:
schema:
type: object
additionalProperties: true
/v1/get-emails-clicked:
post:
operationId: getEmailsClicked
tags:
- Campaigns
summary: Get emails clicked for a campaign
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CampaignReportRequest'
responses:
'200':
description: Emails clicked in the campaign.
content:
application/json:
schema:
type: object
additionalProperties: true
/v1/get-emails-replies:
post:
operationId: getEmailsReplies
tags:
- Campaigns
summary: Get email replies for a campaign
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CampaignReportRequest'
responses:
'200':
description: Email replies in the campaign.
content:
application/json:
schema:
type: object
additionalProperties: true
/v2/sender-accounts/emails:
get:
operationId: listSenderAccounts
tags:
- Sender Accounts
summary: List connected email sender accounts (free)
responses:
'200':
description: Connected sender accounts in the workspace.
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: true
post:
operationId: createSenderAccount
tags:
- Sender Accounts
summary: Connect a new email sender account
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- sender_name
- email_from
- password
- smtp_host
- smtp_port
properties:
sender_name:
type: string
email_from:
type: string
format: email
password:
type: string
smtp_host:
type: string
smtp_port:
type: integer
smtp_encryption:
type: string
enum:
- none
- ssl
- tls
imap_host:
type: string
imap_port:
type: integer
reply_to:
type: string
daily_limitation:
type: integer
signature:
type: string
responses:
'200':
description: The created sender account.
content:
application/json:
schema:
type: object
additionalProperties: true
/v2/sender-accounts/emails/{id}:
patch:
operationId: updateSenderAccount
tags:
- Sender Accounts
summary: Update a sender account
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: The updated sender account.
content:
application/json:
schema:
type: object
additionalProperties: true
/v2/sender-accounts/check-sender-status:
get:
operationId: checkSenderStatus
tags:
- Sender Accounts
summary: Check SMTP/IMAP status of a sender account
parameters:
- name: sender_account_id
in: query
required: true
schema:
type: integer
responses:
'200':
description: Connection validity and any errors.
content:
application/json:
schema:
type: object
additionalProperties: true
/v2/warm-up:
get:
operationId: listWarmUpCampaigns
tags:
- Warm-up
summary: List warm-up campaigns
parameters:
- name: page
in: query
schema:
type: integer
- name: per_page
in: query
schema:
type: integer
- name: status
in: query
schema:
type: string
responses:
'200':
description: Paginated warm-up campaigns.
content:
application/json:
schema:
type: object
additionalProperties: true
post:
operationId: createWarmUpCampaign
tags:
- Warm-up
summary: Create a warm-up campaign
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- sender_account_id
- strategy
properties:
sender_account_id:
type: integer
strategy:
type: string
enum:
- progressive
- steady
daily_goal:
type: integer
reply_rate:
type: number
deadline:
type: string
format: date
responses:
'200':
description: The created warm-up campaign.
content:
application/json:
schema:
type: object
additionalProperties: true
/v2/warm-up/{id}:
get:
operationId: getWarmUpCampaign
tags:
- Warm-up
summary: Get warm-up campaign details
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Warm-up campaign configuration and statistics.
content:
application/json:
schema:
type: object
additionalProperties: true
patch:
operationId: updateWarmUpCampaign
tags:
- Warm-up
summary: Update a warm-up campaign
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: The updated warm-up campaign.
content:
application/json:
schema:
type: object
additionalProperties: true
/v1/get-balance:
get:
operationId: getBalance
tags:
- User
summary: Check the account credit balance (free)
description: Returns the current credit balance and plan usage for the API account.
responses:
'200':
description: The account balance.
content:
application/json:
schema:
$ref: '#/components/schemas/Balance'
components:
parameters:
TaskHashQuery:
name: task_hash
in: query
required: true
description: The task hash returned by the matching /start endpoint.
schema:
type: string
TaskHashPath:
name: task_hash
in: path
required: true
description: The task hash returned by the matching /start endpoint.
schema:
type: string
schemas:
AccessToken:
type: object
properties:
access_token:
type: string
token_type:
type: string
example: Bearer
expires_in:
type: integer
example: 3600
TaskStarted:
type: object
properties:
success:
type: boolean
task_hash:
type: string
status:
type: string
example: in_progress
CampaignReportRequest:
type: object
required:
- campaignId
properties:
campaignId:
type: integer
EmailVerificationResult:
type: object
properties:
success:
type: boolean
data:
type: array
items:
type: object
properties:
email:
type: string
format: email
smtp_status:
type: string
enum:
- valid
- not_valid
- unknown
is_valid_format:
type: boolean
is_disposable:
type: boolean
is_webmail:
type: boolean
is_gibberish:
type: boolean
Balance:
type: object
properties:
success:
type: boolean
balance:
type: string
description: Remaining credits on the account.
teamwork:
type: boolean
limit_hourly:
type: integer
used_hourly:
type: integer
securitySchemes:
OAuth2:
type: oauth2
description: >-
OAuth2 client_credentials flow. POST client_id and client_secret to
/v1/oauth/access_token to obtain a Bearer token, then send it in the
Authorization header.
flows:
clientCredentials:
tokenUrl: https://api.snov.io/v1/oauth/access_token
scopes: {}