Retrieve CSV List & Bulk Validation Status

Retrieve A List Of All CSVs

You can retrieve a list of all CSVs that have been uploaded along with their current state using this API. If you want to download any of the results of a CSV you'll need to use the status API to fetch a list of all available downloads for a CSV. Please call the URL below to retrieve a list of CSVs. Results will be delivered at 50 per page, with the most recent upload displayed first. Optional parameters are listed at the bottom of this page.

This API will return responses that will contain your API key. Treat these responses like passwords and do not share them with third parties.

JSON:

XML:

Optional GET / POST / URL Parameters
Field	Value
type	The type of CSVs to list. (proxy, email, url or phone)
page	The page number of results to return. Each page lists 50 CSVs in order of most recently uploaded.

An example success/failure response is included below.

Example Success Response

When you retrieve the list the result should look like the JSON below. For detailed information on each field see the table at the bottom of this page.

{
    "message": "Success",
    "success": true,
    "csvs": [
        {
            "id": 827748,
            "file_name": "example_email.csv",
            "type": "email",
            "strictness": 0,
            "status": "NEW",
            "aborted": false,
            "invalid_records": 0,
            "status_url": "https://ipqualityscore.com/api/json/csv/YOUR_API_KEY_HERE/status/827748"
        }
    ],
    "total_csvs": 1,
    "total_pages": 1,
    "page": 1,
    "request_id": "HDzXqjnJZ9"
}

Note: You can check the status URL provided to get the current processing status of the CSV. The list API does not return download links for the CSVs displayed. You must query the status URL to get the download link(s). The remainder of the fields are documented on the bulk CSV API processing status documentation.

Example Failure Response

If you specify a wrong type or wrong page, then an error will trigger such as:

{
    "success": false,
    "message": "Invalid type specified. CSV type must be one of: email, proxy, phone or url.",
    "request_id": "HDzi4etwqG"
}

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

csvs

An array/list of CSVs you've requested to be processed by our system. Values for each object in this array are below.

Field

Description

Possible Values

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

status_url

The URL where you can retrieve the current status of this specific CSV and retrieve links to download the results of processing if this CSV is completed.

string/url

array

Example Code

<?php

/*
* Retrieve a list of CSVs.
*/

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

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

// Set the URL to upload a proxy file.
curl_setopt($ch, CURLOPT_URL, 'https://ipqualityscore.com/api/xml/csv/YOUR_API_KEY_HERE/list');

// 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 "List of CSVs retrieved successfully!";

    /*
    * At this point you'll probably want to iterate over the csv array.
    */
    foreach($response['csvs'] as $csv){
        echo "CSV ID: ".$csv['id']." is currently: ".$csv['status']."<br>";
    }
} else {
    echo "CSV upload failed: ".$response['message'];
}