Bulk Uploads Via API

v1 / v2

Bulk Uploads Via API

Overview

Our API can be used to upload large amounts of telephone numbers that customers have saved within a file or by entering large volumes of data in the body of the API request.

Users can use various API commands to upload, view the status, download, pause and schedule their batches. Much like they can when using the Batch Processing page on hlrlookup.com

All batches loaded via the API are downloadable via API or accessible by logging into your account and downloading from there.

Obtain a list of all your batches

Request Type: GET

Curl Example:

By running the above command you’ll see an overview of the available batches listing a unique “ID” for each batch, the filename, the number of lines in the batch and the status to identify the current situation with the batch.

Example Response:

List details of specific batch

To do this you will need to know the 'ID' of the batch. Once you have this you can the 'ID' to your request.

Request Type: GET

Curl Example:

This will return the details specific to that batch ID

Example Response:

Create a new batch

Before you can upload your data you need to first create the batch.

Request Type: POST

Curl Example:

Use the "filename" parameter to add your own filename.

Ensure you use "type": "HLR_V2" so your output file is formatted to include all the features of APIV2

Example Response:

Adding optional parameters

When creating your batch you can also include any of our optional parameters.

These parameters are the same as available using the standard API.

For a list of the available parameters click HERE

To include any of these parameters when creating your batch you need to include "batchArguments" within your request.

Request Type: POST

Curl Example using all optional parameters:

Example Response:

Uploading your data

Once you have created your batch you can either upload your locally stored data as a file or by adding your numbers to the body of the API request.

Loading data from a locally saved file:

To do this include the file path of your file and the batch ID you obtained when creating your batch.

Request Type: POST

Curl Example:

Note - If the numbers you wish to check are saved within your file in a column other than the first column. For example if you have your own internal reference ID in column A and your numbers in column B. Then you can tell the API which column from your file you wish to be checked by appending &column= to the end of the URL.

Numbers Stored In

Mapping Number

Column A

0

Column B

1

Column C

2

Column D

3

Omitting &column= from your request will always result in us checking the data stored in the first column of your file.

Curl example when data is stored in column B of your file:

Example Response:

Loading your data into the body of the API request:

To do this add your numbers into the request body and use batch ID you obtained when creating your batch.

Request Type: POST

Curl Example:

Note - There is a size limit of 2MB which equates to uploads of 100,000 numbers.

Therefore you won’t be able to upload more than 100,000 numbers in one batch when using this method.

Processing your data

Once your data is loaded you can then start the batch by issuing the Processing command as PUT request

Request Type: PUT

Curl Example:

Example Response:

Pausing your batch

Once your data is processing you can then pause your batch by issuing the pause command as PUT request.

Request Type: PUT

Curl Example:

Example Response:

To restart your batch simply run the processing command as before.

Batch scheduling

You can schedule your batch to run at a later time date if required. To do this use the scheduledStart command as a PUT request

Request Type: PUT

Curl Example:

Example Response:

Downloading your results

As with the data upload process, completed batches can be downloaded in 2 ways.

Either in.CSV format or JSON format. To do this use one of the following using the following GET requests:

Download as .CSV

Request Type: GET

Curl Example:

Example Response:

Download in JSON format:

Request Type: GET

Curl Example:

Example Response:

Deleting your batch

If required you can delete you batch by using a DELETE request

Request Type: DELETE

Curl Example:

Example Response:

Deleted batches are non retrievable.

Please ensure you have downloaded your data before issuing the DELETE command.

Error list

The following is a list of errors you may see when trying to upload data via the API

Possible reason:

  • Something wrong with a parameter

Possible reason:

  • Wrong request type - For Example GET used instead of POST

  • Check "filename" / "type" / "HLR_V2" / "scheduledStart" are typed correctly

  • Check you are using the correct Content-Type

  • Check the format of your scheduledStart date

Possible reason

  • 1 or more of your batchArguments are wrong. For a list of the batchArguments you can use check HERE

Possible reason:

  • Check your KEY or SECRET

Possible Reason

  • There's something wrong with the formatting of your request. Check all " " and { } are entered correctly

Possible reason:

  • Wrong batch ID used

Possible reason:

  • You have tried to access that does not belong to you

  • Check secret= and apikey= are typed correctly

Possible reason:

  • You have tried to upload data to a batch that already has data loaded to it.