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.

https://ipqualityscore.com/api/json/csv/YOUR_API_KEY_HERE/status/YOUR_CSV_ID

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=example.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"
}

Retrieving Responses via Webhook

Alternatively, you can set up a webhook to automatically receive the results as soon as your CSV has finished processing.

Setting up a Webhook

Log into the IPQS dashboard.
From the Settings & Account Management menu in the navigation bar on the left, select Account Settings.
At the top, select the User Webhooks tab.
On the right, click the + (plus) button.
From the Type dropdown menu, select CSV Batch.
In the Hook URL field, enter the URL for your webhook. Webhook URLs must be valid, start with "https", and have a valid TLS certificate.
Click Update Webhooks.

Example Webhook Response

When the API has finished processing your CSV, your webhook will receive a response similar to this:

{
  "extra_data": null,
  "result_url": "https://downloads.ipqualityscore.com/download?download=...&filename=example.csv",
  "result": {
    <The result of a GET call to the result_url, or null if there was an error. See "Response Field Definitions" below for a list of result fields and definitions.>
  }
  "type": "csv"
}

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

status fields

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.

downloads fields

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.

<?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 1,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