Bulk API Documentation

Check Bulk Verification CSV Status

Once you've uploaded your CSV for processing, you'll likely want to retrieve the current status of the processing until the CSV has finished processing. This bulk verification API returns the status of your CSVs which are processing or completed. Once a bulk upload has finished processing, the status will display as "FINISHED" along with a series of one-time download links which can be used to retrieve the results.

Download links are only valid for 15 minutes from the time you request this API or when the link is downloaded, whichever comes first.

Each request to this API will result in fresh links being made available if the CSV has finished processing.

Download links contain a one-time use authentication key which WILL NOT require login to retrieve. Treat these links like passwords!

JSON:

You must supply the CSV ID in the request URL or via POST parameters.

Example Success Response

When you finish uploading a file a successful response should look like this:

{
    "message": "Success",
    "success": true,
    "id": 827750,
    "file_name": "test.csv",
    "type": "proxy",
    "strictness": 0,
    "status": "FINISHED",
    "aborted": false,
    "invalid_records": 0,
    "downloads": {
        "pristine": null,
        "clean": null,
        "bad": null,
        "all": "https://downloads.ipqualityscore.com/download?download=...&filename=test.csv",
    },
    "request_id": "HE1BDCGjmf"
}

Once your file has finished processing downloads will contain links to retrieve your results.

Example Failure Response

If we're unable to retrieve data about your chosen CSV or there's another issue, you may receive an error response such as:

{
    "success": false,
    "message": "Invalid CSVID provided. Please check your CSVID and try again.",
    "request_id": "HE33ch5VSJ"
}

Response Field Descriptions

Field

Description

Possible Values

message

Messages about the status of your request to include potential errors.

string

success

True if this request was successful, false if unsuccessful.

boolean

The unique, numeric, ID of the file being processed.

int64

file_name

The name of the file or an automatically generated name if no name was specified during upload.

string

type

The type of CSV that was uploaded. Value can be: "proxy", "url", "email", or "phone".

string/enum

strictness

The strictness level of this file's processing. (Integer 0 - 3, 0 = default). We recommend the default strictness level.

int

status

The current status of the CSV's processing.

Value	Description
NEW	The CSV is waiting to begin processing. This status should be fairly short lived under normal operating conditions.
PROCESSING	The CSV is currently processing through records.
UNIQUE_RESULTS	The CSV is currently being uniqued to remove duplicate records.
FINALIZING	The CSV is currently undergoing final checks before processing completes.
FINISHED	The CSV is finished processing and is ready for download.

string/enum

aborted

True if processing on this CSV was cancelled before completion.

boolean

invalid_records

The current number of invalid records detected in the CSV.

int

downloads

A list of available download links. Unavailable or impossible links will return null.

URL Field	Description
pristine	Link to download the pristine results for this CSV. Pristine results vary by API, but typically are records that are extremely clean. This link may not be available for every type of CSV upload.
clean	Link to download all of the clean results for this CSV. This link may not be available for every type of CSV upload.
bad	Link to download all of the bad/invalid/unclean results for this CSV. This link may not be available for every type of CSV upload.
all	Link to download ALL results for this CSV. Should be available on all CSVs with a status of FINISHED.

Example Code

<?php

/*
* Retrieve a list of CSVs.
*/

$csv_id = 1111; // Your CSV ID

//Initialise the cURL var
$ch = curl_init();

//Get the response from cURL
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set the URL to retrieve the status page.
curl_setopt($ch, CURLOPT_URL, 'https://ipqualityscore.com/api/xml/csv/YOUR_API_KEY_HERE/status/'.$csv_id);

// Execute the request
$raw_response = curl_exec($ch);

// Decode the response.
$response = json_decode($raw_response, true);

// Print out the result or error.
if($response['success']){
    echo "CSV status:".$response['status'];

    // Check if the CSV is finished.

    if($response['status'] === 'FINISHED'){
        echo "CSV is finished processing! Downloading!";

        /*
        * At this point you'll probably want to download the results.
        */

        file_put_contents($response['file_name'], file_get_contents($response['downloads']['all']));
    } else {
        echo "CSV is not finished.";
    }

} else {
    echo "CSV status request failed: ".$response['message'];
}