OpenAPI Specification
openapi: 3.0.3
info:
title: Snov.io Authentication Prospects 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: Prospects
description: Manage prospect records and lists
paths:
/v1/add-prospect:
post:
tags:
- Prospects
summary: Add prospect to list
description: Add a new prospect record to a prospect list.
operationId: addProspect
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectCreate'
responses:
'201':
description: Prospect added
content:
application/json:
schema:
$ref: '#/components/schemas/Prospect'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/find-prospect-by-id:
post:
tags:
- Prospects
summary: Find prospect by ID
operationId: findProspectById
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: string
description: Prospect ID
responses:
'200':
description: Prospect details
content:
application/json:
schema:
$ref: '#/components/schemas/Prospect'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/find-prospect-by-email:
post:
tags:
- Prospects
summary: Find prospect by email
operationId: findProspectByEmail
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: string
format: email
responses:
'200':
description: Prospect details
content:
application/json:
schema:
$ref: '#/components/schemas/Prospect'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/prospect-custom-fields:
get:
tags:
- Prospects
summary: Get prospect custom fields
description: Returns all custom fields defined for prospects.
operationId: getProspectCustomFields
security:
- bearerAuth: []
responses:
'200':
description: Custom fields
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
type:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
/v1/user-lists:
get:
tags:
- Prospects
summary: List prospect lists
description: Returns all prospect lists for the user.
operationId: listProspectLists
security:
- bearerAuth: []
responses:
'200':
description: Prospect lists
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ProspectList'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/view-prospects-in-list:
post:
tags:
- Prospects
summary: View prospects in list
description: Returns prospects belonging to a specific prospect list.
operationId: viewProspectsInList
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- list_id
properties:
list_id:
type: integer
page:
type: integer
default: 1
per_page:
type: integer
default: 20
responses:
'200':
description: Prospects in list
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Prospect'
total:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
/v1/create-prospect-list:
post:
tags:
- Prospects
summary: Create prospect list
description: Create a new prospect list.
operationId: createProspectList
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: Name for the new prospect list
responses:
'201':
description: Prospect list created
content:
application/json:
schema:
$ref: '#/components/schemas/ProspectList'
'401':
$ref: '#/components/responses/Unauthorized'
components:
responses:
Unauthorized:
description: Unauthorized — missing or invalid Bearer token
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Bad request — missing or invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Prospect:
type: object
properties:
id:
type: string
email:
type: string
format: email
first_name:
type: string
last_name:
type: string
position:
type: string
company:
type: string
location:
type: string
custom_fields:
type: object
additionalProperties: true
ProspectList:
type: object
properties:
id:
type: integer
name:
type: string
count:
type: integer
created_at:
type: string
format: date-time
ProspectCreate:
type: object
required:
- email
- list_id
properties:
email:
type: string
format: email
first_name:
type: string
last_name:
type: string
position:
type: string
company:
type: string
company_website:
type: string
format: uri
location:
type: string
phone:
type: string
linkedin:
type: string
format: uri
list_id:
type: integer
custom_fields:
type: object
additionalProperties: true
Error:
type: object
properties:
error:
type: string
description: Error code
message:
type: string
description: Human-readable error message
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Obtain a Bearer token via POST /v1/oauth/access_token using client credentials. Tokens expire after 3600 seconds.