OpenAPI Specification
openapi: 3.1.0
info:
title: NeverBounce API v4 Account Jobs API
version: '4'
description: 'RESTful JSON API for email verification. Provides single email verification and bulk list (jobs) verification endpoints. Authentication uses a per-integration API key (format `secret_xxxx...`) supplied via the `key` query/body parameter or the `Authorization: Bearer` header.'
contact:
name: NeverBounce Developers
url: https://developers.neverbounce.com/
servers:
- url: https://api.neverbounce.com/v4
description: NeverBounce v4 production API
security:
- ApiKeyQuery: []
- BearerAuth: []
tags:
- name: Jobs
description: Bulk list verification jobs
paths:
/jobs/create:
post:
tags:
- Jobs
summary: Create a verification job
description: Creates a bulk verification job from either a remote URL containing a CSV/list of emails or from inline supplied data.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobCreateRequest'
responses:
'200':
description: Job created
content:
application/json:
schema:
$ref: '#/components/schemas/JobCreateResponse'
/jobs/parse:
post:
tags:
- Jobs
summary: Parse a previously uploaded job
description: Begins parsing of an uploaded list to prepare it for verification.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- job_id
properties:
key:
type: string
job_id:
type: integer
auto_start:
type: boolean
responses:
'200':
description: Parse acknowledgement
/jobs/start:
post:
tags:
- Jobs
summary: Start verification of a parsed job
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- job_id
properties:
key:
type: string
job_id:
type: integer
run_sample:
type: boolean
responses:
'200':
description: Start acknowledgement
/jobs/status:
get:
tags:
- Jobs
summary: Get job status
parameters:
- name: key
in: query
required: false
schema:
type: string
- name: job_id
in: query
required: true
schema:
type: integer
responses:
'200':
description: Job status
content:
application/json:
schema:
$ref: '#/components/schemas/JobStatusResponse'
/jobs/results:
get:
tags:
- Jobs
summary: Get paginated job results
parameters:
- name: key
in: query
required: false
schema:
type: string
- name: job_id
in: query
required: true
schema:
type: integer
- name: page
in: query
required: false
schema:
type: integer
- name: items_per_page
in: query
required: false
schema:
type: integer
responses:
'200':
description: Paginated job results
/jobs/download:
get:
tags:
- Jobs
summary: Download completed job results as CSV
parameters:
- name: key
in: query
required: false
schema:
type: string
- name: job_id
in: query
required: true
schema:
type: integer
- name: valids
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
- name: invalids
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
- name: disposables
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
- name: catchalls
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
- name: unknowns
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
responses:
'200':
description: CSV download
content:
text/csv: {}
components:
schemas:
JobCreateResponse:
type: object
properties:
status:
type: string
job_id:
type: integer
execution_time:
type: integer
JobStatusResponse:
type: object
properties:
status:
type: string
id:
type: integer
job_status:
type: string
enum:
- under_review
- queued
- failed
- complete
- running
- parsing
- waiting
- waiting_analyzed
- uploading
total:
type: object
additionalProperties: true
bounce_estimate:
type: number
percent_complete:
type: number
created_at:
type: string
format: date-time
JobCreateRequest:
type: object
required:
- input
- input_location
properties:
key:
type: string
input:
description: Either a remote URL or an inline list of email rows
oneOf:
- type: string
- type: array
items:
type: array
items:
type: string
input_location:
type: string
enum:
- remote_url
- supplied
filename:
type: string
auto_parse:
type: boolean
auto_start:
type: boolean
run_sample:
type: boolean
allow_manual_review:
type: boolean
request_meta_data:
type: object
properties:
leverage_historical_data:
type: integer
enum:
- 0
- 1
securitySchemes:
ApiKeyQuery:
type: apiKey
in: query
name: key
BearerAuth:
type: http
scheme: bearer
externalDocs:
description: NeverBounce API getting started
url: https://developers.neverbounce.com/docs/api-getting-started