API Reference

Progress of a bulk validation list

get https://api.validto.com/v1/bulk/

The current status of the list can be obtained using this endpoint. The system analyses your uploaded list automatically and identifies all disposable, syntax and spam trap emails. If the status of the list is 'ready', you can initiate the verification of the bulk list. Then, if the status of the list is 'completed', you can download the results of the bulk list.

Response

HTTP/1.1 200 OK
{
    "job_id": "pb49raml26hlkyuaykopl6wtg58k6vssq5t0w",
    "status": "completed",
    "created_at": "09/19/2021, 09:08:26 AM",
    "total": 3,
    "verified": 3,
    "pending": 0,
    "analysis": {
        "common_isp": 2,
        "role_based": 1,
        "disposable": 0,
        "spamtrap": 0,
        "syntax_error": 0
    },
    "results": {
        "deliverable": 2,
        "undeliverable": 0,
        "accept_all": 1,
        "unknown": 0
    },
    "success": true,
    "message": "Verification completed successfully. Please download the result using /download endpoint"
}

Response parameters

ParameterTypeDefinition
"job_id"[string]The job_id corresponding to the list you need to check the status
"status"[string]The status of the list
"created_at"[date time]The date and time in which the list has been created
"total"[Integer]The total number of emails the list has
"verified"[Integer]The number of emails are verified
"pending"[Integer]The number of emails need to be verified
"common_isp"[0, 1]Whether the email is hosted by a free email provider like Gmail, Yahoo!, Hotmail etc..
"role_based"[0, 1]Whether the email is considered a role address. (e.g. "sales@, info@, help@, etc.)
"disposable"[0, 1]Whether this is a temporary email.
"spamtrap"[0, 1]Is this a honey-trap email
"syntax_error"[0, 1]Whether the email is syntactically incorrect
"deliverable"[Integer]These emails are valid and safe to send mail.
"undeliverable"[Integer]Sending mails will result in bounce.
"accept_all"[Integer]Remote host accepts mail at any address.
"unknown"[Integer]Unable to definitively verify these emails as their mail servers were not reachable during verification.
"success"[true, false]Whether the API request call was successful or not.
"message"[string]Describes API result

Other Responses

The response you get when the API key is invalid:

HTTP/1.1 401 Unauthorized
{   
   "result":"Invalid API Key",
   "success": false
}

The response you get when you provide invalid job_id:

HTTP/1.1 400 BadRequest
{
    "result": "Job not found. Invalid jobId",
    "success": false
}

The response you get still the job is preparing:

HTTP/1.1 200 OK
{
    "job_id": "pb49raml26hlkyuaykopl6wtg58k6vssq5t0w",
    "status": "preparing",
    "created_at": "09/19/2021, 09:08:26 AM",
    "success": true,
    "message": "Job is being prepared for verification"
}

The response you get when the list is ready for verification:

HTTP/1.1 200 OK
{
    "job_id": "pb49raml26hlkyuaykopl6wtg58k6vssq5t0w",
    "status": "ready",
    "created_at": "09/19/2021, 09:08:26 AM",
    "total": 3,
    "analysis": {
        "common_isp": 2,
        "role_based": 1,
        "disposable": 0,
        "spamtrap": 0,
        "syntax_error": 0
    },
    "success": true,
    "message": "Job ready for verification. Please begin verification to know the result"
}

The response you get when the list is in verifying status:

HTTP/1.1 200 OK
{
    "job_id": "pb49raml26hlkyuaykopl6wtg58k6vssq5t0w",
    "status": "verifying",
    "created_at": "09/19/2021, 09:08:26 AM",
    "total": 3,
    "verified": 2,
    "pending": 1,
    "analysis": {
        "common_isp": 2,
        "role_based": 1,
        "disposable": 0,
        "spamtrap": 0,
        "syntax_error": 0
    },
    "results": {
        "deliverable": 1,
        "undeliverable": 0,
        "accept_all": 1,
        "unknown": 0
    },
    "success": true,
    "message": "Job is being verified"
}

The response you get when the job failed:

HTTP/1.1 200 OK
{
    "job_id": "pb49raml26hlkyuaykopl6wtg58k6vssq5t0w",
    "status": "failed",
    "created_at": "09/19/2021, 10:16:47 AM",
    "total": 0,
    "success": true,
    "message": "Unable to process your job, The uploaded list contains invalid data"
}

The response you get when the job is cancelled:

HTTP/1.1 200 OK
{
    "job_id": "pb49raml26hlkyuaykopl6wtg58k6vssq5t0w",
    "status": "cancelled",
    "created_at": "09/20/2021, 10:20:35 AM",
    "total": 4,
    "success": true,
    "message": "Job is cancelled"
}

The response you get when the job not found:

HTTP/1.1 400 BadRequest
{
    "result": "Job not found",
    "success": false
}
Language