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 Pipeline

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 is 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 toward your usage. When initially testing your integration, it is recommended to use small batch sizes (less than 10 contacts).

📘

Usage Guidelines

Be sure to review our usage guidelines for working with the API here.

1. Adding a List

We currently support uploading files by supplying either a URL to a CSV file or by supplying the data directly in the body of the request. Below we'll go over both methods.

Sending a CSV by URL

The URL submitted must lead directly to the file and contain the protocol, as well as any authentication credentials the request needs. See the remote url section in the reference docs for more information about the protocols and acceptable authentication methods. The URL should be sent in the request as the input parameter with the input_location should be set to remote_url. Below is an example request:

curl --request POST\
  --url https://api.neverbounce.com/v4/jobs/create\
  --data key={api_key}\
  --data input_location='remote_url'\
  --data filename='SampleNeverBounceAPI.csv'\
  --data auto_parse=1\
  --data auto_start=1\
  --data input='https://mydomain.com/my_file.csv'

Sending data directly

Data submitted directly should exist as an array of arrays or an array of objects. See the supplied data section for more information. The data should be sent in the request as the input parameter with the input_location should be set to supplied. Below is an example of this request:

curl --request POST\
  --header "Content-Type: application/json"\
  --url https://api.neverbounce.com/v4/jobs/create\
  --data '{
    "key": {api_key},
    "input_location": "supplied",
    "filename": "SampleNeverBounceAPI.csv",
    "auto_start": 1,
    "auto_parse": 1,
    "input": [
        [
            "[email protected]",
            "Fred McValid"
        ],
        [
            "[email protected]",
            "Bob McInvalid"
        ]
    ]
}'

curl --request POST\
  --url https://api.neverbounce.com/v4/jobs/create\
  --data key={api_key}\
  --data input_location='supplied'\
  --data filename='SampleNeverBounceAPI.csv'\
  --data auto_parse=1\
  --data auto_start=1\
  --data 'input[0][0]=support%40neverbounce.com'\
  --data 'input[0][1]=Fred%20McValid'\
  --data 'input[1][0]=invalid%40neverbounce.com'\
  --data 'input[1][1]=Bob%20McInvalid'

After the request

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.

📘

Read more about the bulk endpoint here.

{
  "status": "success",
  "job_id": 150970,
  "execution_time": 712
}

Once you receive a response, you will 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.

2. Checking the status

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.

curl --request GET\
  --url 'https://api.neverbounce.com/v4/jobs/status?key={api_key}&job_id={job_id}'

📘

Read more about the status endpoint here.

{
    "status": "success",
    "id": 185137,
    "filename": "NBUser_1054_58f2b406006f1",
    "created": "2017-04-15 20:00:06",
    "started": "2017-04-15 20:00:21",
    "finished": "2017-04-15 21:52:46",
    "total_records": 24606,
    "total_billable": 24606,
    "total_processed": 24606,
    "total_valid": 18227,
    "total_invalid": 1305,
    "total_catchall": 4342,
    "total_disposable": 16,
    "total_unknown": 716,
    "total_duplicates": 0,
    "total_bad_syntax": 0,
    "bounce_estimate": 5.3035844915874,
    "percent_complete": 100,
    "job_status": "complete",
    "execution_time": 2535
}

In the response, the job_status parameter will indicate what the list is currently doing. Typically, status will be the only parameter you will need to watch. However, you may find the fields starting with total_ useful for seeing a breakdown of the results in your list while it’s processing.

Once the job_status value is set to complete, you’re ready to retrieve the results.

3. Retrieving the Results

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

curl --request GET\
  --url 'https://api.neverbounce.com/v4/jobs/download?key={api_key}&job_id={job_id}'

📘

Read more about the download endpoint and all the available parameters here.

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.

"[email protected]","Fred McValid",valid
"[email protected]","Bob McInvalid",invalid