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
Method 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
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:
