Bulk processing API documentation

Content

API usage rules

Number of emails
The maximum allowed number of emails is 50,000.
Result storing
The result is stored for 7 days.
Cost
1 credit per email

Making requests

POSThttps://emailverification.whoisxmlapi.com/api/bevService/

In order to check lists of emails with the Bulk API, first upload the emails to the server which will create a verification request and return its ID to you. Then you can use this ID to query the request's status, download results etc.

The API expects parameters to be JSON-encoded in the body of each request.

Headers

Content-Type
application/json

Create a new verification request

POSThttps://emailverification.whoisxmlapi.com/api/bevService/request

CURL request sample

        curl https://emailverification.whoisxmlapi.com/api/bevService/request -X POST -H "Content-Type: application/json"  -d '{"apiKey": "YOUR_API_KEY", "emails": ["alex@hotmail.edu", "bob@google.com", "mila@yahoo.com"], "format": "json"}'
    

POST request body sample

        {
    "apiKey": "YOUR_API_KEY",
    "emails": [
        "alex@hotmail.edu",
        "bob@google.com",
        "mila@yahoo.com"
    ],
    "format": "json"
}
    

Input parameters

apiKey
Required. String.

Get your personal API KEY on My products page.
emails
Required. Array.

Contains array of email addresses for verification.
format
Optional. String.

Used to specify the response format.

Allowed values: "xml", "json", "csv".

Default value: "json".

Sample output

                            {
    "response": {
        "id": 5
    }
}

Code: 200 OK.
                            {
    "response": {
        "errors": [
            "The format field should have one of the following values: json, xml."
        ]
    }
}

Code: 400 Bad Request.
                            {
    "response": {
        "error": "Authorisation or authentication failed"
    }
}

Code: 401 Unauthorized.
                            {
    "response": {
        "error": "Insufficient balance"
    }
}

Code: 402 Payment Required.
response
The response object.

Contains the integer "id" field on success.

In case of an error it contains its description in the "error" field. If there are multiple errors their descriptions are returned in the "errors" array.
id
Integer.

Newly created verification request ID.
error
String.

Error description.
errors
Array.

Multiple error messages.

Get a list of your requests

POSThttps://emailverification.whoisxmlapi.com/api/bevService/request/list

CURL request sample

        curl https://emailverification.whoisxmlapi.com/api/bevService/request/list -X POST -H "Content-Type: application/json"  -d '{"apiKey": "YOUR_API_KEY", "page": 1, "onlyIds": false, "perPage": 10, "sort": "desc", "format": "json"}'
    

POST request body sample

        {
    "apiKey": "YOUR_API_KEY",
    "page": 1,
    "format": "json",
    "onlyIds": false,
    "perPage": 10,
    "sort": "desc"
}
    

Input parameters

apiKey
Required. String.

Get your personal API KEY on My products page.
page
Optional. Integer.

Used to paginate the result sets in conjunction with "perPage".

Default value: 1.
format
Optional. String.

Used to specify the response format.

Allowed values: "xml", "json", "csv".

Default value: "json".
onlyIds
Optional. Boolean.

When it's true only the list of IDs is returned.

Default value: true.
perPage
Optional. Integer.

Limits each page of the result-set to this number of requests.

Min: 10; Max: 50.

Default value: 10
sort
Optional. String.

Specify the order of requests in the response.

Allowed values: "asc", "desc".

Default value: "desc".

Sample output

                            {
    "response": {
        "current_page": 1,
        "data": [
            {
                "id": 596
            },
            {
                "id": 595
            },
            {
                "id": 544
            }
        ],
        "from": 1,
        "last_page": 1,
        "per_page": 10,
        "to": 3,
        "total": 3
    }
}

Code: 200 OK.
                            {
    "response": {
        "current_page": 1,
        "data": [
            {
                "id": 596,
                "date_start": "1528377253",
                "total_emails": 3,
                "invalid_emails": 0,
                "processed_emails": 3,
                "failed_emails": 0,
                "ready": 1
            },
            {
                "id": 595,
                "date_start": "1528377227",
                "total_emails": 20,
                "invalid_emails": 0,
                "processed_emails": 20,
                "failed_emails": 0,
                "ready": 1
            },
            {
                "id": 544,
                "date_start": "1528204702",
                "total_emails": 500,
                "invalid_emails": 0,
                "processed_emails": 500,
                "failed_emails": 0,
                "ready": 1
            }
        ],
        "from": 1,
        "last_page": 1,
        "per_page": 10,
        "to": 3,
        "total": 3
    }
}

Code: 200 OK.
response
The response object.

Contains the "data" field with an array of user's requests' data on success.

The "from" and "to" fields represent the result set's ID range of the requests returned for the current page.

"per_page" is the pages' size and "total" is the number of requests in the result set.

The "current_page" and "last_page" correspond to the number of pages in the result set.

In case of an error it contains its description in the "error" field. If there are multiple errors their descriptions are returned in the "errors" array.
data
Array.

A list of your requests' info elements (if "onlyIds" is true, each element has only the "id" field).
data[k].id
The response object.

Request ID.
data[k].date_start
String.

String representation of the request's start Unix timestamp.
data[k].total_emails
Integer.

The total of number of emails in the request.
data[k].invalid_emails
Integer.

Number of invalid emails.
data[k].processed_emails
Integer.

Number of already processed email addresses.
data[k].failed_emails
Integer.

Number of emails that could not be processed.
data[k].ready
Integer.

1 if processing has finished, 0 – otherwise.
from
Integer.

Min. request ID in the current page of the data set.
to
Integer.

Max. request ID in the current page of the data set.
per_page
Integer.

Max. number of requests for each page of the result set.
total
Integer.

The total number of requests in the result set.
current_page
Integer.

Current page number in the result set.
last_page
Integer.

The number of the last page in the set.
error
String.

Error description.
errors
Array.

Multiple error messages.

Get request's status

POSThttps://emailverification.whoisxmlapi.com/api/bevService/request/status

CURL request sample

        curl https://emailverification.whoisxmlapi.com/api/bevService/request/status -X POST -H "Content-Type: application/json"  -d '{"apiKey": "YOUR_API_KEY", "ids": [622], "format": "json"}'
    

POST request body sample

        {
    "apiKey": "YOUR_API_KEY",
    "ids": [544, 595, 596],
    "format": "json"
}
    

Input parameters

apiKey
Required. String.

Get your personal API KEY on My products page.
ids
Required. Array.

Required requests' IDs.
format
Optional. String.

Used to specify the response format.

Allowed values: "xml", "json", "csv".

Default value: "json".

Sample output

                            {
    "response": [
        {
            "id": 544,
            "date_start": "1528204702",
            "total_emails": 500,
            "invalid_emails": 0,
            "processed_emails": 500,
            "failed_emails": 0,
            "ready": 1
        },
        {
            "id": 595,
            "date_start": "1528377227",
            "total_emails": 20,
            "invalid_emails": 0,
            "processed_emails": 20,
            "failed_emails": 0,
            "ready": 1
        },
        {
            "id": 596,
            "date_start": "1528377253",
            "total_emails": 3,
            "invalid_emails": 0,
            "processed_emails": 3,
            "failed_emails": 0,
            "ready": 1
        }
    ]
}

Code: 200 OK.
response
The response object.

Contains an array of user's requests' info on success. This array can be empty in case the "ids" array contains non-existing ids only.

In case of an error it contains its description in the "error" field. If there are multiple errors their descriptions are returned in the "errors" array.

Get results (processed emails)

POSThttps://emailverification.whoisxmlapi.com/api/bevService/request/completed

CURL request sample

        curl https://emailverification.whoisxmlapi.com/api/bevService/request/completed -X POST -H "Content-Type: application/json"  -d '{"apiKey": "YOUR_API_KEY", "id": 622, "format": "json"}'
    

POST request body sample

        {
    "apiKey": "YOUR_API_KEY",
    "id": 596,
    "format": "csv"
}
    

Input parameters

apiKey
Required. String.

Get your personal API KEY on My products page.
id
Required. Integer.

ID of the request.
format
Optional. String.

Used to specify the response format.

Allowed values: "xml", "json", "csv".

Default value: "json".

Sample output

                            {
    "response": [
        {
            "emailAddress": "alex@alex.edu",
            "formatCheck": "true",
            "smtpCheck": "null",
            "dnsCheck": "false",
            "freeCheck": "false",
            "disposableCheck": "false",
            "catchAllCheck": "null",
            "result": "bad"
        },
        {
            "emailAddress": "bob@google.com",
            "formatCheck": "true",
            "smtpCheck": "true",
            "dnsCheck": "true",
            "freeCheck": "false",
            "disposableCheck": "false",
            "catchAllCheck": "true",
            "mxRecords": [
                "alt2.aspmx.l.google.com",
                "alt3.aspmx.l.google.com",
                "alt4.aspmx.l.google.com",
                "aspmx.l.google.com",
                "alt1.aspmx.l.google.com"
            ],
            "result": "unknown"
        },
        {
            "emailAddress": "mila@yahoo.com",
            "formatCheck": "true",
            "smtpCheck": "true",
            "dnsCheck": "true",
            "freeCheck": "true",
            "disposableCheck": "false",
            "catchAllCheck": "true",
            "mxRecords": [
                "mta6.am0.yahoodns.net",
                "mta5.am0.yahoodns.net",
                "mta7.am0.yahoodns.net"
            ],
            "result": "unknown"
        }
    ]
}

Code: 200 OK.
                            {
    "response": {
        "error": "Wrong request id"
    }
}

Code: 422 Unprocessable Entity.
response
The response object.

Contains an array of verification results for each email address in the original request. See the documentation to get more info.

Responses to these request can be saved directly to disk.

In case of an error it contains its description in the "error" field. If there are multiple errors their descriptions are returned in the "errors" array.

Get results (Invalid and failed emails)

POSThttps://emailverification.whoisxmlapi.com/api/bevService/request/failed

CURL request sample

        curl https://emailverification.whoisxmlapi.com/api/bevService/request/failed -X POST -H "Content-Type: application/json"  -d '{"apiKey": "YOUR_API_KEY", "id": 622, "format": "json"}'
    

POST request body sample

        {
    "apiKey": "YOUR_API_KEY",
    "id": 596,
    "format": "csv"
}
    

Input parameters

apiKey
Required. String.

Get your personal API KEY on My products page.
id
Required. Integer.

ID of the request.
format
Optional. String.

Used to specify the response format.

Allowed values: "xml", "json", "csv".

Default value: "json".

List of possible errors

400 Bad Request
Some required fields are missing from the request's body or have invalid values.
401 Unauthorized
The required "apiKey" field value is missing or invalid.
402 Payment Required
Insufficient API queries account balance.
403 Forbidden
The request you're trying to access doesn't belong to your account.
422 Unprocessable Entity
The request you're trying to access doesn't belong to your account.
5XX
Internal server error, please contact our support team.

Try Email Verification API for free

Have questions?
support@whoisxmlapi.com
We will get back to you within a day.
WHOIS API, Inc.

California
USA

Contact us