Skip to content
ValidationCheck

Start a bulk job

POST
/v1/bulk/jobs
curl --request POST \
  --url https://api.validationcheck.net/v1/bulk/jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "type": "email", "inputs": [ "example" ], "name": "example", "country": "example", "smtp": true }'

Checks up to 100,000 inputs of one type in the background. Duplicates and blanks are folded (free). The job reserves one credit per unique input when it starts (402 INSUFFICIENT_CREDITS and nothing starts if you don’t have them), so it can’t run out partway through; free answers and repeats are returned when it finishes. Get a bulk.completed webhook, or poll GET /v1/bulk/jobs/{id}.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
type
required
string
Allowed values: email phone phone_type ip domain_age email_auth
inputs
required
Array<string>
>= 1 items <= 100000 items
name
string
<= 200 characters
country

Default country for phone numbers without a + prefix.

string
>= 2 characters <= 2 characters
smtp

Emails: set false to skip mailbox checks.

boolean

Responses

Section titled “Responses”

202

Section titled “202”

Started

Media typeapplication/json
object
success
required
boolean
data
required
object
id
required
string
name
required
string
type
required
string
Allowed values: email phone phone_type ip domain_age email_auth
status
required
string
Allowed values: queued running completed cancelled failed
total_rows
required
number
unique_inputs
required
number
processed
required
number
credits_used
required
number
results
required
object
approve
required
number
verify
required
number
review
required
number
block
required
number
errors
required
number
skipped
required
number
cache_hits
required
number
created_at
required
string
completed_at
required
string | null
expires_at
required

Results and files are deleted 7 days after the job was created.

string

Example 

{
  "success": true,
  "data": {
    "type": "email",
    "status": "queued"
  }
}

400

Section titled “400”

Error

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required
string
Allowed values: INVALID_REQUEST INVALID_INPUT MISSING_FIELD UNAUTHORIZED INSUFFICIENT_CREDITS FORBIDDEN_SCOPE ACCOUNT_SUSPENDED NOT_FOUND IDEMPOTENCY_CONFLICT INPUT_LIMIT_EXCEEDED RATE_LIMITED INTERNAL_ERROR UPSTREAM_UNAVAILABLE MAINTENANCE
message
required
string
docs_url
required
string format: uri
request_id
required
string

Example 

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST"
  }
}

401

Section titled “401”

Error

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required
string
Allowed values: INVALID_REQUEST INVALID_INPUT MISSING_FIELD UNAUTHORIZED INSUFFICIENT_CREDITS FORBIDDEN_SCOPE ACCOUNT_SUSPENDED NOT_FOUND IDEMPOTENCY_CONFLICT INPUT_LIMIT_EXCEEDED RATE_LIMITED INTERNAL_ERROR UPSTREAM_UNAVAILABLE MAINTENANCE
message
required
string
docs_url
required
string format: uri
request_id
required
string

Example 

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST"
  }
}

402

Section titled “402”

Error

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required
string
Allowed values: INVALID_REQUEST INVALID_INPUT MISSING_FIELD UNAUTHORIZED INSUFFICIENT_CREDITS FORBIDDEN_SCOPE ACCOUNT_SUSPENDED NOT_FOUND IDEMPOTENCY_CONFLICT INPUT_LIMIT_EXCEEDED RATE_LIMITED INTERNAL_ERROR UPSTREAM_UNAVAILABLE MAINTENANCE
message
required
string
docs_url
required
string format: uri
request_id
required
string

Example 

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST"
  }
}

403

Section titled “403”

Error

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required
string
Allowed values: INVALID_REQUEST INVALID_INPUT MISSING_FIELD UNAUTHORIZED INSUFFICIENT_CREDITS FORBIDDEN_SCOPE ACCOUNT_SUSPENDED NOT_FOUND IDEMPOTENCY_CONFLICT INPUT_LIMIT_EXCEEDED RATE_LIMITED INTERNAL_ERROR UPSTREAM_UNAVAILABLE MAINTENANCE
message
required
string
docs_url
required
string format: uri
request_id
required
string

Example 

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST"
  }
}

404

Section titled “404”

Error

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required
string
Allowed values: INVALID_REQUEST INVALID_INPUT MISSING_FIELD UNAUTHORIZED INSUFFICIENT_CREDITS FORBIDDEN_SCOPE ACCOUNT_SUSPENDED NOT_FOUND IDEMPOTENCY_CONFLICT INPUT_LIMIT_EXCEEDED RATE_LIMITED INTERNAL_ERROR UPSTREAM_UNAVAILABLE MAINTENANCE
message
required
string
docs_url
required
string format: uri
request_id
required
string

Example 

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST"
  }
}

413

Section titled “413”

Error

Media typeapplication/json
object
success
required
boolean
error
required
object
code
required
string
Allowed values: INVALID_REQUEST INVALID_INPUT MISSING_FIELD UNAUTHORIZED INSUFFICIENT_CREDITS FORBIDDEN_SCOPE ACCOUNT_SUSPENDED NOT_FOUND IDEMPOTENCY_CONFLICT INPUT_LIMIT_EXCEEDED RATE_LIMITED INTERNAL_ERROR UPSTREAM_UNAVAILABLE MAINTENANCE
message
required
string
docs_url
required
string format: uri
request_id
required
string

Example 

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST"
  }
}