Bulk API Documentation

Bulk Verification CSV API Uploading

IPQualityScore supports bulk CSV file uploading via multiple methods: HTTP POST file upload, URL file retrieval and JSON. All of these upload methods work via the same URL, but may require additional parameters. Each upload method is covered below in more detail. Allowed file types are: "proxy", "email", "phone", or "url". Example code is provided on the side menu for different methods of uploading data.

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:

Note: You may optionally remove the key and type of file from the URL and pass them in as POST/GET/JSON parameters instead. In which case the URL would look like this:

JSON:

HTTP Post / File Upload

To upload via POST / form file upload, please include the headers below with your request. If you don't include these headers then it's likely your file upload will fail. Include one file in the body of your request with any key. The request must be form-data encoded.

Headers
Field	Value
Content-Type	multipart/form-data
Content-Length	«calculated when request is sent»

GET / POST / URL Parameters
Field	Value
key	Your API Key
type	The type of CSV ("proxy", "email", "url", or "phone")
file_name	An optional name for this file. A name will automatically be generated if none is supplied.

An example success/failure response is included below.

Upload Via URL

You can upload your file by providing us with the file's download URL via either GET or POST parameters. Your URL MUST lead directly to the file, MUST include the protocol (http/https/ftp) and MUST include any authentication methods in the URL.

GET / POST Parameters
Field	Value
key	Your API Key
type	The type of CSV (proxy, email, url or phone)
input OR url	The full link to download the file you wish to process.
file_name	An optional name for this file. A name will automatically be generated if none is supplied.

An example success/failure response is included below.

Upload Via JSON

You can upload your data for processing via JSON. Below is an example request and example JSON structure.

Headers
Field	Value
Content-Type	application/json

JSON Body / Data
{ "type": "email", "file_name": "example.csv", "key": "YOUR_API_KEY_HERE", "input": [ [ "support@ipqualityscore.com", "James", "Brown" ], [ "support@ipqualityscore.com", "John", "McDonald" ] ] }

An example success/failure response is included below. * file_name is optional.

Example Success Response

This is an example of a successful API response after uploading a file.

{
    "message": "Success",
    "success": true,
    "id": 827746,
    "file_name": "sample_emails.csv",
    "type": "email",
    "strictness": 0,
    "status": "NEW",
    "aborted": null,
    "invalid_records": 0,
	"status_url": "https://ipqualityscore.com/api/json/csv/YOUR_API_KEY_HERE/status/827748",
    "downloads": {
        "pristine": null,
        "clean": null,
        "bad": null,
        "all": null
    },
    "request_id": "HDOgXxgMHJ"
}

Once your file has uploaded you can check the status URL provided to get the current status of the CSV. The remainder of the fields are documented on the Bulk CSV API Processing Status Documentation.

Example Failure Response

If your CSV fails to upload for some reason then you should receive an error message detailing why. For further troubleshooting steps see the troubleshooting documentation page.

{
    "success": false,
    "message": "Invalid CSV URL specified. Please check the URL and try again. Error code: 8",
    "request_id": "HDWmnOD9oK"
}

Example Code

<?php

/*
* Example 1: uploading a proxy file on disk
* directly to the Bulk CSV Processing API.
*/

//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/proxy/upload');

// Create a POST array with the file in it
$postData = array(
    'file' => '@/path/to/file.txt',
);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

// 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 uploaded successfully!";
} else {
    echo "CSV upload failed: ".$response['message'];
}

/*
* At this point you'll probably want to retrieve the status
* of your CSV and download the results. For those code examples
* you'll want to visit our other documentation pages:
*
* https://{Settings::Get()->Value(['site', 'domain'])}/documentation/csv-api/check-csv-status
* https://{Settings::Get()->Value(['site', 'domain'])}/documentation/csv-api/download-csv-results
*/

<?php

/*
* Example 2: uploading a JSON (array) to 
* the Bulk CSV Processing API.
*/

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

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

// Set the required headers specifying this is a JSON request.
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-type: application/json"));

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

// Create a POST array that will be converted into JSON.
$postData = [
    'input' => [
        [
            "support@ipqualityscore.com",
            "James",
            "Brown"
        ],
        [
            "support@ipqualityscore.com",
            "John",
            "McDonald"
        ]
    ]
];

// Make this a POST request.
curl_setopt($ch, CURLOPT_POST, true);

// Encode $postData into json
$json = json_encode($postData);

// Send the JSON to the server.
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);

// 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 uploaded successfully!";
} else {
    echo "CSV upload failed: ".$response['message'];
}

/*
* At this point you'll probably want to retrieve the status
* of your CSV and download the results. For those code examples
* you'll want to visit our other documentation pages:
*
* https://{Settings::Get()->Value(['site', 'domain'])}/documentation/csv-api/check-csv-status
* https://{Settings::Get()->Value(['site', 'domain'])}/documentation/csv-api/download-csv-results
*/

<?php

/*
* Example 3: sending a link for us to download your CSV.
*/

//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/proxy/upload');

// Create a POST array that contains a link to download our file.
$postData = [
    'url' => 'https://www.ipqualityscore.com/downloads/sample_proxy.csv'
];

// Make this a POST request.
curl_setopt($ch, CURLOPT_POST, true);

// Encode the POST data.
$data = http_build_query($postData);

// Send the data to the server.
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

// 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 uploaded successfully!";
} else {
    echo "CSV upload failed: ".$response['message'];
}

/*
* At this point you'll probably want to retrieve the status
* of your CSV and download the results. For those code examples
* you'll want to visit our other documentation pages:
*
* https://{Settings::Get()->Value(['site', 'domain'])}/documentation/csv-api/check-csv-status
* https://{Settings::Get()->Value(['site', 'domain'])}/documentation/csv-api/download-csv-results
*/