Find and retrieve email addresses for prospects by domain, name, or LinkedIn profile URL. Supports domain search, name-based email lookup, LinkedIn profile enrichment, and generic company contact discovery. Operations follow an async start/result pattern.
openapi: 3.0.3
info:
title: Snov.io API
description: >-
Snov.io is a sales automation and lead generation platform. The REST API
enables programmatic access to email finding, domain search, email
verification, drip campaign management, email warm-up, prospect management,
CRM pipeline, and webhook subscriptions. Authentication uses OAuth 2.0
client credentials to obtain short-lived Bearer tokens. All API operations
consume credits from the account balance.
version: '2.0'
contact:
name: Snov.io Support
url: https://snov.io/knowledgebase/
termsOfService: https://snov.io/terms-of-service/
license:
name: Proprietary
url: https://snov.io/terms-of-service/
servers:
- url: https://api.snov.io
description: Snov.io API server
tags:
- name: Authentication
description: OAuth 2.0 token management
- name: Domain Search
description: Search for company information and email addresses by domain
- name: Email Finder
description: Find email addresses by name, LinkedIn, or domain
- name: Email Verification
description: Verify email deliverability and validity
- name: Email Accounts
description: Manage sender email accounts
- name: Email Warm-up
description: Manage email warm-up campaigns for improved deliverability
- name: Campaigns
description: Create and manage multi-channel outreach campaigns
- name: Prospects
description: Manage prospect records and lists
- name: CRM Pipeline
description: CRM pipeline and stage management
- name: Webhooks
description: Real-time event webhook subscriptions
- name: User
description: User account management
paths:
# ─── Authentication ───────────────────────────────────────────────────────
/v1/oauth/access_token:
post:
tags:
- Authentication
summary: Get access token
description: >-
Obtain a short-lived Bearer token using OAuth 2.0 client credentials
flow. Tokens expire after 3600 seconds.
operationId: getAccessToken
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- grant_type
- client_id
- client_secret
properties:
grant_type:
type: string
enum:
- client_credentials
example: client_credentials
client_id:
type: string
description: Client ID from account settings
client_secret:
type: string
description: Client secret from account settings
responses:
'200':
description: Access token issued
content:
application/json:
schema:
$ref: '#/components/schemas/AccessToken'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
# ─── Domain Search ────────────────────────────────────────────────────────
/v2/domain-search/start:
post:
tags:
- Domain Search
summary: Start domain search
description: >-
Initiate an async domain search. Returns a task_hash to retrieve results.
Costs 1 credit per unique domain request.
operationId: startDomainSearch
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
properties:
domain:
type: string
description: Company domain name to search
example: example.com
responses:
'200':
description: Task started
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/domain-search/result/{task_hash}:
get:
tags:
- Domain Search
summary: Get domain search results
description: Retrieve results of a previously started domain search task.
operationId: getDomainSearchResult
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/TaskHash'
responses:
'200':
description: Domain search results
content:
application/json:
schema:
$ref: '#/components/schemas/DomainSearchResult'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v2/domain-search/prospects/start:
post:
tags:
- Domain Search
summary: Start domain prospect search
description: Initiate an async search for prospect profiles associated with a domain.
operationId: startDomainProspectSearch
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
properties:
domain:
type: string
example: example.com
positions:
type: array
items:
type: string
description: Filter by job positions
example:
- CEO
- CTO
page:
type: integer
description: Page number for pagination
default: 1
responses:
'200':
description: Task started
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/domain-search/prospects/result/{task_hash}:
get:
tags:
- Domain Search
summary: Get domain prospect search results
operationId: getDomainProspectSearchResult
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/TaskHash'
responses:
'200':
description: Prospect search results
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectListResult'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/domain-search/domain-emails/start:
post:
tags:
- Domain Search
summary: Start domain emails search
description: Initiate an async search for all email addresses associated with a domain.
operationId: startDomainEmailsSearch
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
properties:
domain:
type: string
example: example.com
responses:
'200':
description: Task started
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/domain-search/domain-emails/result/{task_hash}:
get:
tags:
- Domain Search
summary: Get domain emails search results
operationId: getDomainEmailsSearchResult
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/TaskHash'
responses:
'200':
description: Domain emails results
content:
application/json:
schema:
$ref: '#/components/schemas/EmailListResult'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/domain-search/generic-contacts/start:
post:
tags:
- Domain Search
summary: Start generic contacts search
description: Initiate an async search for generic company contact addresses (e.g. info@, support@).
operationId: startGenericContactsSearch
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
properties:
domain:
type: string
example: example.com
responses:
'200':
description: Task started
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/domain-search/generic-contacts/result/{task_hash}:
get:
tags:
- Domain Search
summary: Get generic contacts search results
operationId: getGenericContactsSearchResult
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/TaskHash'
responses:
'200':
description: Generic contacts results
content:
application/json:
schema:
$ref: '#/components/schemas/EmailListResult'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/get-domain-emails-count:
post:
tags:
- Domain Search
summary: Check available emails count (free)
description: Returns the count of available email addresses for a domain. Free endpoint.
operationId: getDomainEmailsCount
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
properties:
domain:
type: string
example: example.com
responses:
'200':
description: Email count for domain
content:
application/json:
schema:
type: object
properties:
domain:
type: string
result:
type: integer
description: Number of available emails
'401':
$ref: '#/components/responses/Unauthorized'
# ─── Email Finder ─────────────────────────────────────────────────────────
/v2/emails-by-domain-by-name/start:
post:
tags:
- Email Finder
summary: Start find emails by name and domain
description: >-
Find email addresses by providing first name, last name, and domain.
Costs 1 credit per valid or unknown email found.
operationId: startFindEmailsByName
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- rows
properties:
rows:
type: array
description: Array of name+domain rows to look up
items:
type: object
required:
- first_name
- last_name
- domain
properties:
first_name:
type: string
example: John
last_name:
type: string
example: Doe
domain:
type: string
example: example.com
webhook_url:
type: string
format: uri
description: Optional webhook URL to receive results when ready
responses:
'200':
description: Task started
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/emails-by-domain-by-name/result:
get:
tags:
- Email Finder
summary: Get find emails by name results
operationId: getFindEmailsByNameResult
security:
- bearerAuth: []
parameters:
- name: task_hash
in: query
required: true
schema:
type: string
description: Task hash returned from the start endpoint
responses:
'200':
description: Email finder results
content:
application/json:
schema:
$ref: '#/components/schemas/EmailFinderResult'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/company-domain-by-name/start:
post:
tags:
- Email Finder
summary: Start find domain by company name
description: >-
Find company domains by company name. Costs 1 credit per domain found.
operationId: startFindDomainByCompanyName
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- names
properties:
names:
type: array
items:
type: string
description: List of company names to look up
example:
- Acme Corp
- Example Inc
webhook_url:
type: string
format: uri
responses:
'200':
description: Task started
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/company-domain-by-name/result:
get:
tags:
- Email Finder
summary: Get find domain by company name results
operationId: getFindDomainByCompanyNameResult
security:
- bearerAuth: []
parameters:
- name: task_hash
in: query
required: true
schema:
type: string
responses:
'200':
description: Company domain lookup results
content:
application/json:
schema:
type: object
properties:
status:
type: string
data:
type: array
items:
type: object
properties:
name:
type: string
domain:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
/v2/li-profiles-by-urls/start:
post:
tags:
- Email Finder
summary: Start LinkedIn profile enrichment
description: >-
Enrich LinkedIn profiles by URL. Costs 1 credit per profile retrieved.
operationId: startLinkedInProfileEnrichment
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- urls
properties:
urls:
type: array
items:
type: string
format: uri
description: LinkedIn profile URLs
example:
- https://www.linkedin.com/in/johndoe
webhook_url:
type: string
format: uri
responses:
'200':
description: Task started
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/li-profiles-by-urls/result:
get:
tags:
- Email Finder
summary: Get LinkedIn profile enrichment results
operationId: getLinkedInProfileEnrichmentResult
security:
- bearerAuth: []
parameters:
- name: task_hash
in: query
required: true
schema:
type: string
responses:
'200':
description: LinkedIn profile enrichment results
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectListResult'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/get-profile-by-email:
post:
tags:
- Email Finder
summary: Enrich profile by email
description: >-
Retrieve prospect profile information by email address. Costs 1 credit
per request; free if no results are found.
operationId: getProfileByEmail
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
example: [email protected]
responses:
'200':
description: Prospect profile data
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectProfile'
'401':
$ref: '#/components/responses/Unauthorized'
# ─── Email Verification ───────────────────────────────────────────────────
/v2/email-verification/start:
post:
tags:
- Email Verification
summary: Start email verification
description: >-
Initiate async verification of up to 10 email addresses. Returns a
task_hash to poll for results.
operationId: startEmailVerification
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- emails
properties:
emails:
type: array
maxItems: 10
items:
type: string
format: email
example:
- [email protected]
- [email protected]
webhook_url:
type: string
format: uri
responses:
'200':
description: Task started
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStarted'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/email-verification/result:
get:
tags:
- Email Verification
summary: Get email verification results
operationId: getEmailVerificationResult
security:
- bearerAuth: []
parameters:
- name: task_hash
in: query
required: true
schema:
type: string
responses:
'200':
description: Email verification results
content:
application/json:
schema:
type: object
properties:
status:
type: string
data:
type: array
items:
$ref: '#/components/schemas/EmailVerificationResult'
'401':
$ref: '#/components/responses/Unauthorized'
# ─── Email Accounts ───────────────────────────────────────────────────────
/v2/sender-accounts/emails:
get:
tags:
- Email Accounts
summary: List email accounts (free)
description: Returns all connected sender email accounts with status information.
operationId: listEmailAccounts
security:
- bearerAuth: []
responses:
'200':
description: List of email accounts
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/EmailAccount'
'401':
$ref: '#/components/responses/Unauthorized'
post:
tags:
- Email Accounts
summary: Add email account
description: Connect a new sender email account with SMTP/IMAP configuration.
operationId: addEmailAccount
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmailAccountCreate'
responses:
'201':
description: Email account created
content:
application/json:
schema:
$ref: '#/components/schemas/EmailAccount'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/sender-accounts/emails/{id}:
patch:
tags:
- Email Accounts
summary: Update email account
description: Update an existing sender email account configuration.
operationId: updateEmailAccount
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Email account ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmailAccountUpdate'
responses:
'200':
description: Email account updated
content:
application/json:
schema:
$ref: '#/components/schemas/EmailAccount'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v2/sender-accounts/check-sender-status:
get:
tags:
- Email Accounts
summary: Check sender account status
description: >-
Check SMTP and IMAP connection status for a sender account.
Returns pending/valid/invalid status with error messages if applicable.
operationId: checkSenderStatus
security:
- bearerAuth: []
parameters:
- name: sender_account_id
in: query
required: true
schema:
type: string
description: ID of the sender account to check
responses:
'200':
description: Sender account status
content:
application/json:
schema:
type: object
properties:
smtp_status:
type: string
enum:
- pending
- valid
- invalid
imap_status:
type: string
enum:
- pending
- valid
- invalid
smtp_error:
type: string
nullable: true
imap_error:
type: string
nullable: true
'401':
$ref: '#/components/responses/Unauthorized'
# ─── Email Warm-up ────────────────────────────────────────────────────────
/v2/warm-up:
get:
tags:
- Email Warm-up
summary: List warm-up campaigns
description: Returns a paginated list of all email warm-up campaigns.
operationId: listWarmUpCampaigns
security:
- bearerAuth: []
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: per_page
in: query
schema:
type: integer
enum:
- 20
- 50
- 100
default: 20
- name: status
in: query
schema:
type: string
description: Filter by campaign status
responses:
'200':
description: Paginated list of warm-up campaigns
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/WarmUpCampaign'
total:
type: integer
page:
type: integer
per_page:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
post:
tags:
- Email Warm-up
summary: Create warm-up campaign
description: Create a new email warm-up campaign to improve deliverability scores.
operationId: createWarmUpCampaign
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WarmUpCampaignCreate'
responses:
'201':
description: Warm-up campaign created
content:
application/json:
schema:
$ref: '#/components/schemas/WarmUpCampaign'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/warm-up/{id}:
get:
tags:
- Email Warm-up
summary: Get warm-up campaign
description: Retrieve full details of a specific warm-up campaign.
operationId: getWarmUpCampaign
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/CampaignId'
responses:
'200':
description: Warm-up campaign details
content:
application/json:
schema:
$ref: '#/components/schemas/WarmUpCampaign'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
tags:
- Email Warm-up
summary: Update warm-up campaign
description: Update settings of an existing warm-up campaign.
operationId: updateWarmUpCampaign
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/CampaignId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WarmUpCampaignUpdate'
responses:
'200':
description: Warm-up campaign updated
content:
application/json:
schema:
$ref: '#/components/schemas/WarmUpCampaign'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
# ─── Campaigns ────────────────────────────────────────────────────────────
/v1/user-campaigns:
get:
tags:
- Campaigns
summary: List campaigns
description: Returns all multi-channel outreach campaigns for the user.
operationId: listCampaigns
security:
- bearerAuth: []
responses:
'200':
description: List of campaigns
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Campaign'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/create-campaign:
post:
tags:
- Campaigns
summary: Create campaign
description: Create a new multi-channel outreach campaign.
operationId: createCampaign
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignCreate'
responses:
'201':
description: Campaign created
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/campaign/{id}:
get:
tags:
- Campaigns
summary: Get campaign
description: Retrieve details of a specific campaign by ID.
operationId: getCampaign
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/CampaignId'
responses:
'200':
description: Campaign details
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
tags:
- Campaigns
summary: Update campaign
description: Update an existing campaign's settings.
operationId: updateCampaign
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/CampaignId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignCreate'
responses:
'200':
description: Campaign updated
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
tags:
- Campaigns
summary: Delete campaign
description: Permanently delete a campaign.
operationId: deleteCampaign
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/CampaignId'
responses:
'204':
description: Campaign deleted
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/campaign/{id}/state:
post:
tags:
- Campaigns
summary: Change campaign state
description: Start, pause, or stop a campaign.
operationId: changeCampaignState
security:
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/CampaignId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- state
properties:
state:
type: string
enum:
- start
- pause
- stop
responses:
'200':
description: State changed
content:
application/json:
schema:
# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/snov-io/refs/heads/main/openapi/snov-io-openapi.yml