Verifying a List

❗️

This version has been depreciated

Existing integrations using this API will continue to work as usual. However, new integrations should be created using the V4 API. We will continue to support this API for the foreseeable future but will not be adding new features to it.​

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

1. Adding a List

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 an 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.

curl -X POST https://api.neverbounce.com/v3/bulk\
    -d access_token={access_token}\
    -d input_location=0\
    -d input={url}

📘

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

📘

Read more about the bulk endpoint here.

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.

{
  "success": true,
  "job_id": 194459,
  "job_status": 0,
  "job_file": "2017-04-26.api_job.1054.590102fbcae30.csv",
  "execution_time": 0.60870909690857
}

Once you get 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 -X POST https://api.neverbounce.com/v3/status\
    -d access_token={access_token}\
    -d version=3.1\
    -d job_id={job_id}

📘

Read more about the status endpoint here.

{
  "success": true,
  "id": "194459",
  "status": "4",
  "type": "1",
  "input_location": "1",
  "orig_name": "2017-04-26.api_job.1054.590102fbcae30.csv",
  "stats": {
    "total": 1,
    "processed": 1,
    "valid": 1,
    "invalid": 0,
    "catchall": 0,
    "disposable": 0,
    "unknown": 0,
    "duplicates": 0,
    "bad_syntax": 0,
    "billable": 1,
    "job_time": 0
  },
  "created": "2017-04-26 16:28:43",
  "started": "2017-04-26 16:28:40",
  "finished": "2017-04-26 16:28:40",
  "analysis_started": null,
  "analysis_finished": null,
  "indexing_started": "2017-04-26 16:28:44",
  "indexing_finished": "2017-04-26 16:28:44",
  "last_touched": "2017-04-26 16:28:40",
  "file_details": "{\"error\":false,\"email_col_i\":0,\"tot_cols\":1,\"delimiter\":\"\",\"has_header\":false,\"linefeed_type\":\"LINEFEED_0A\",\"quote_type\":\"QUOTE_DOUBLE\",\"delimiter_type\":\"DELIM_COMMA\",\"binary_options_type\":\"BIN_1_0\",\"size\":20,\"tot_records\":2,\"tot_emails\":0}",
  "execution_time": 0.015229940414429
}

In the response, the 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 stats object useful for seeing a breakdown of the results in your list while it’s processing. You can also use the processed and total 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.

3. Retrieving the Results

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

curl -X POST https://api.neverbounce.com/v3/download\
    -d access_token={access_token}\
    -d job_id={job_id}

📘

Read more about the download endpoint 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],valid
[email protected],invalid