Verifying a List

With the NeverBounce API you are able to verify your existing contact lists without ever needing to upload a list to the dashboard.

The PipelineAnchor

Verifying a list through the API is similar to uploading and verifying a list through the dashboard. Once the list has been received, we begin by indexing and deduping it followed by the verification process. Depending on the list size this can take a while. It’s for this reason that verification results are not available immediately in the list submission response. In order to get results you will need to periodically poll the API to check on the status of the verification process until it is completed. Once it has completed you can retrieve the results. Below is a flowchart illustrating the pipeline for verifying a list.


Note: Lists added via this endpoint will start the verification process immediately and will count towards your usage. When initially testing your integration it is recommended to use small batch sizes (less than 10 contacts).

Adding a ListAnchor

To get started you first need to aggregate your data into a CSV format. Each row can only contain a single email and all emails should be in the same column.

Click here to learn more about formatting your list.

Once aggregated this list can be submitted either directly as a URL encoded string or by submitting a public URL to the CSV. For larger lists the latter method is preferred. If you receive a 413 Request Entity Too Large http error, you should try submitting a public URL to the CSV instead.

When you submit a list via the API the verification process will start automatically. If your credit balance is insufficient the verification of your list will fail. You can purchase credits in bulk from the dashboard or submit a request to use our monthly billing option. You can also choose to run a free analysis rather than verifying your list, see here.

Here’s an example request:

curl -X POST\
    -d access_token=<ACCESSTOKEN>\
    -d input_location=0\
    -d input=<URL>\
    -d filename=<FILENAME>

Unsure where to get an access_token? Click here to find out how to generate one.

With input_location set to 0 our API will assume the input parameter contains a URL to the list. Setting input_location to 1 tells the API that the input parameter contains a URL encoded string of the contents of your list. The third parameter filename is optional, but we do suggest supplying it as it will be useful for identifying your list in the dashboard.

Example Response:

    "success": true,
    "job_status": 0,
    "job_id": 22099,
    "execution_time": 0.16023087501526

Once you get a response you’ll want to store the value of job_id, as it will be used to check the status and eventually retrieve the results. Now you’re ready to start checking the status of the verification.

Checking the statusAnchor

Now that your list is running, you will need to poll the API and check the status periodically. For smaller lists (<50k) polling every 5-10 seconds is acceptable, but for larger lists (>50k) you’ll want to poll less frequently.

Example Request

curl -X POST\
    -d access_token=<ACCESS TOKEN>\
    -d version=3.1\
    -d job_id=<JOB ID>

Example Response
    "success": true,
    "id": "00000",
    "status": "3",
    "type": "1",
    "input_location": "1",
    "orig_name": "Filename",
    "stats": {
        "total": 100,
        "processed": 20,
        "valid": 0,
        "invalid": 0,
        "bad_syntax": 0,
        "catchall": 0,
        "disposable": 0,
        "unknown": 0,
        "duplicates": 0,
        "billable": 2,
        "job_time": 15
    "created": "2016-02-09 16:28:19",
    "started": "2016-02-09 16:28:34",
    "finished": "2016-02-09 16:28:49",
    "file_details": "{\"error\":false,\"email_col_i\":0,\"tot_cols\":1,\"delimiter\":\"\",\"has_header\":false,\"size\":39,\"tot_records\":3,\"tot_emails\":2}",
    "job_details": [],
    "execution_time": 0.0692138671875

In the response, the status parameter will indicate what the list is currently doing. You can find a table of status codes below. Typically status will be the only parameter you will need to watch. However, you may find the stats object useful for seeing a breakdown of the results in your list while it’s processing. You can also use the processed and billable values in the stats object to track the progress of the verification.

Once the status value is 4 you’re ready to retrieve the results.

Status Codes

Value Description
0 Request has been received but has not started idexing
1 List is indexing and deduping
2 List is awaiting user input (Typically skipped for lists submitted via API)
3 List is being processed
4 List has completed verification
5 List has failed (Click here to learn how to fix a failed list)

Retrieving the ResultsAnchor

Now with verfication completed it’s time to see the results.

Example Request:

curl -X POST\
    -d access_token=<ACCESS TOKEN>\
    -d job_id=<JOB ID>\
    -d valids=1\
    -d invalids=1\
    -d catchall=1\
    -d disposable=1\
    -d unknown=1\
    -d duplicates=1\
    -d textcodes=1

All of the parameters in the above request are optional aside from access_token and job_id. When all parameters are omitted they will default to 1. If only some parameters are specified but others are omitted, the omitted parameters will default to 0.

Parameter Description
valids Include valid emails
invalids Include invalid emails
catchall Include catchall emails
disposable Include disposable emails
unknown Include unknown emails
duplicates Include duplicated emails (duplicates will have the same verification result)
textcodes Result codes will be returned as english words instead of numbers

Example Response:,valid,invalid

The data will be returned in a CSV format with the last column containing the result codes. This will look familiar if you’ve verified a list through the dashboard.