Validity BriteVerify Bulk Verification API is a simple, RESTful web service that developers can access via the back-end API key, the same way they would access our Real-Time Email API. It also allows for viewing the file status and results for files submitted.

Creating a New Bulk List Job

To submit email addresses to us for verification, send a POST request with your API key as a parameter and your data in the POST body like this:

POST 

http://app.briteverify.com/api/v1/public/list_jobs?apikey=  

POST Body:

{ "name": "name-of-file-to-export.csv", "emails": ["john.doe@doesnotexist.com",”john.doe@doesnotexist.com"] }

Headers:

Content-Type: application/json

The API will respond with your verification job information:

{ "id": 1649, 
"name": " name-of-file-to-export.csv ",  
"status": "pending",
"total_verified": 0,
"percent_complete": 0 }

List Job Status

Not Completed Jobs

Once you have the job’s data, you can then poll the API for your job’s status by issuing a GET 

http://app.briteverify.com/api/v1/public/list_jobs/?apikey=<your-api-key>

You’ll get back the up-to-date status of your job:

{ "id": 1649, 
"name": "name-of-file-to-export.csv",
"status": "verifying",
"total_verified": 89252,
"percent_complete": 72 }

Finished List Jobs

After the job completes:

GET

https://app.briteverify.com/api/v1/public/list_jobs/<job_id>.csv?apikey=<api_key>

(specifying CSV as the format will produce a csv file download, see Response Formats)

{
"id": 36,
"name": " name-of-file-to-export.csv ",
"status": "complete",
"total_verified": 5,
"percent_complete": 100,
"results": [{"email": "john.doe@doesnotexist.com",
"email_status": "unknown",
"secondary_status": null},
{"email": "john.doe@doesnotexist.com",
"email_status": "invalid",
"secondary_status": "email_account_invalid"}]
}

Viewing All List Jobs

To see a list of all your Bulk API jobs, you can send a GET request like the one above. 

GET 

http://app.briteverify.com/api/v1/public/list_jobs/?apikey=<your-api-key>

You can optionally filter the results to show only jobs matching a specific status by adding an optional parameter: 

GET 

http://app.briteverify.com/api/v1/public/list_jobs/?apikey=<your-api-key>&status=<status>

Available statuses you can use to sort by are:

  • processing
  • uploading
  • pending
  • prepped
  • loading
  • verifying
  • exporting
  • complete
  • deleted

The API will respond with an array of the jobs:

[
{
"id": 18,
"name": "5.csv",
"total_verified": 1,
"status": "complete"
},
{
"id": 19,
 "name": "5.csv",
"total_verified": 1,
"status": "complete"
},
{ "id": 20,
 "name": "5.csv",
"total_verified": 1,
"status": "complete"
}
]

Delete a List Job

To do a soft delete of a job (marked as deleted, job meta-data persists). 

DELETE

http://app.briteverify.com/api/v1/public/list_jobs/<job_id>/?apikey=<your-api-key>

The API will respond with success/failure of the delete:

{"message": "Action completed successfully" }


Response Formats

Our Bulk API can respond with the following formats:

  • JSON (application/json)
  • CSV (application/csv) **

To request a specific format, add the parameter to your request URL (json in this example):

GET 

http://app.briteverify.com/api/v1/public/list_jobs.json?apikey=<your-api-key>

NOTE:
 
*Please note that the format CSV will return a downloadable .csv file. If you need a text-based response, we recommend JSON.

**CSV is only supported as file download for finished jobs. Other endpoints will default to JSON if CSV is called for.

Account Minimums & Maximums

  • Because this API is meant for processing large batches of data for verification, it has a minimum job size of 10,000 records and a maximum size of 1,000,000 records per job for CSV format.
  • For JSON response formats, a minimum job size of 10,000 records and a maximum size of 100,000 records per job is acceptable.  
  • Each account allows for upto 10 simultaneously processing Bulk API jobs
Did this answer your question?