<< Back to Categories

Checking Status & Downloading Results

About

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

Note: If the CSV has finished processing, each request to this API will generate new download links. Download links are only valid for 15 minutes from when you request this API or until you download the results, whichever comes first.

Warning: Download links contain a one-time-use authentication key that will not require login to retrieve. Treat these links like passwords.

Request URL

Replace YOUR_CSV_ID with the specific ID for your CSV. You must supply the CSV ID in the request URL or via POST parameters.

Example Responses

Success Response

This is an example success response in JSON format. Responses are also available in XML format.

{
    "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"
}

Failure Response

This is an example failure response you would receive after submitting an invalid CSV ID.

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

Response Field Definitions

Field

Description

Possible Values

message

Messages about the status of your request, including potential errors.

string

success

Was the request successful?

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

aborted

Was the processing on this CSV 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".

Next Steps

You can retrieve a list of all CSV you have uploaded.

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'];
}

Ready to eliminate fraud?

Start fighting fraud now with 5,000 Free Lookups!

We're happy to answer any questions or concerns.

Chat with our fraud detection experts any day of the week.

Call us at: (800) 713-2618

Schedule a Demo Sign Up