Knowledge Base

Batch uploads using our API

You can use the API to upload a batch of numbers.

All results are made available on the batch upload page on a user’s account with the ability to also download through the API.

A successful upload will give you a batch ID. You use this ID to issue further commands.

Base URL     https://www.hlrlookup.com/api/bulk

Metho          POST

Header Content-type: application/x-www-form-urlencoded

Parameters

Ensure the following parameters are in the request body and in a form encoded format.

Header Type Information
batchname String A friendly reference name for your batch
data Blob List your numbers, split by comma and in their international format. There is a maximum post size limit of 50MB
start String An optional parameter, if set to "yes" the batch will be processed immediately if not then it will be left in a "holding" status until you call /process
personalcache String A value between 0 and 30 which relates to the number of days you want to check against your Personal Cache
sharedcache String A value between 0 and 30 which relates to the number of days you want to check against the Global Cache
savetoshared String Set to 'on' to save this result to the Global Cache of results. Set to 0 or 'off' to not save your result

Examples

The Target URL is:

https://www.hlrlookup.com/api/bulk/?apikey=$key&password=$password

The Request Body Needs:

batchname=test&data=447541255456,447856999555,447854111222&start=yes

This will start your request.

If you want to add the optional cache parameters to your request include them in the request body like this:

batchname=test&data=447541255456,447856999555,447854111222&start=yes&personalcache=30

&sharedcache=15&savetoshared=on

Note: Replace $key and $password with your own details. Your $key can be found in your account settings.

Example Response:

A successful request will give you a “batchid” which can be used to issue further commands.

{"status":"OK","batchid":8690}

Please refer to our API Error List pages if do not see an “OK” response.

Further Commands

/process

Starts an existing batch for processing. Use this command when start=yes was omitted from the initial API request.

Base URL      https://www.hlrlookup.com/api/process/{batch}

Method         GET

Parameters – Replace {batch} with the batchid returned from the initial request

Example – https://www.hlrlookup.com/api/process/8690?apikey=$key&password=$password

Example JSON Response:

{"status":"OK"}


/pause

Use this command to pause a batch that is currently running.

Base URL    https://www.hlrlookup.com/api/pause/{batch}

Method       GET

Parameters – Replace {batch} with the batchid returned from the initial request.

Example – https://www.hlrlookup.com/api/pause/8690?apikey=$key&password=$password

Example JSON response:

{"status":"OK"}

Hint – To restart a paused batch use the /process command


/status

Use this command to return an overview of the current status of your batch

Base URL     https://www.hlrlookup.com/api/status/{batch}

Method        GET

Parameters – Replace {batch} with the batchid returned from the initial request.

Example – https://www.hlrlookup.com/api/status/8690?apikey=$key&password=$password

Example JSON response:

"batchid": "8690",
"status": "Processing",
"total_records": "5000",
"records_remaining": "4000",
"percentage_complete": "20.00"


/download

Use this command to download your data once your batch is complete.

Base URL     https://www.hlrlookup.com/api/download/{batch}

Method        GET

Parameters – Replace {batch} with the batchid returned from the initial request

Example Response: