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.
Contains array of email addresses for verification.
format
Optional. String.
Used to specify the response format.
Allowed values: "xml", "json", "csv".
Default value: "json".
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.
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.
Newly created verification request ID.
error
String.
Error description.
Error description.
errors
Array.
Multiple error messages.
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.
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".
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.
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
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".
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.
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).
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.
Request ID.
data[k].date_start
String.
String representation of the request's start Unix timestamp.
String representation of the request's start Unix timestamp.
data[k].total_emails
Integer.
The total of number of emails in the request.
The total of number of emails in the request.
data[k].invalid_emails
Integer.
Number of invalid emails.
Number of invalid emails.
data[k].processed_emails
Integer.
Number of already processed email addresses.
Number of already processed email addresses.
data[k].failed_emails
Integer.
Number of emails that could not be processed.
Number of emails that could not be processed.
data[k].ready
Integer.
1 if processing has finished, 0 – otherwise.
1 if processing has finished, 0 – otherwise.
from
Integer.
Min. request ID in the current page of the data set.
Min. request ID in the current page of the data set.
to
Integer.
Max. request ID in the current page of the data set.
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.
Max. number of requests for each page of the result set.
total
Integer.
The total number of requests in the result set.
The total number of requests in the result set.
current_page
Integer.
Current page number in the result set.
Current page number in the result set.
last_page
Integer.
The number of the last page in the set.
The number of the last page in the set.
error
String.
Error description.
Error description.
errors
Array.
Multiple error messages.
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.
Required requests' IDs.
format
Optional. String.
Used to specify the response format.
Allowed values: "xml", "json", "csv".
Default value: "json".
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.
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.
ID of the request.
format
Optional. String.
Used to specify the response format.
Allowed values: "xml", "json", "csv".
Default value: "json".
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.
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.
ID of the request.
format
Optional. String.
Used to specify the response format.
Allowed values: "xml", "json", "csv".
Default value: "json".
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