File Upload API

Send us your customer data files via our API

Sending us your customer data via our File Upload API can be easier and more flexible than SFTP or manual file upload. Here we’ll guide you to creating your API token, requesting permission to deliver a file, and sending that file. Note: you can also send us files via Secure File Upload drag and drop.

API Token

API tokens can be created within Manage > Integrations. Click on the ‘API Tokens’ tile and ‘New API Token’. Once you provide a description and click ‘Save’ the token will be made visible to you. Ensure you save the token at this point because it cannot be viewed again.

Note: your account can have up to 5 active API tokens.

Upload Files

Sending your file is done in two steps. First you must authenticate and request permission to send your file, which responds with a destination URL. Next you use this URL to send us your data file.

1. Request permission to send your file

Run the following command after replacing <TOKEN> with your API Token retrieved from Integrate, and updating <FILE_NAME> with your .csv or .json file.

curl -XPOST -H 'Auth-Api-Token: <TOKEN>' -H 'Content-type: application/json' -d '{"filename": "<FILE_NAME>"}'

A successful request will return a response that looks like this:

{ id: 123, url: "https://lexer-client-upload-au..." }

The URL field is where you will be sending your file. Copy the URL for use in the next step.

2. Send your file

Run the command below with the URL inserted from the response above, as well as your file name.

curl -XPUT "<URL>" --upload-file <FILE_NAME>

Done! Our team will receive a notification that your file has been received, and we will reach out with any questions or issues. We advise getting in touch to let us know you have sent the file.

File Details

  • File size maximum is 5GB.
  • File format preference is CSV or JSON.


Please note that the URL received from first request contains \u0026 in place of &. Having the ampersand represented as hexadecimal can cause the second request to return an error similar to that below.

<?xml version="1.0" encoding="UTF-8"?><Error><Code>AuthorizationQueryParametersError</Code><Message>X-Amz-Algorithm only supports "AWS4-HMAC-SHA256"</Message><RequestId>...</RequestId><HostId>...+.../....=</HostId></Error>

This can be avoided by saving the URL in a variable as demonstrated in the workflow below.

url=$(curl -XPOST -H 'Auth-Api-Token:<TOKEN>' -H 'Content-type: application/json' -d '{"filename": "<FILE_NAME>"}' | jq -r .url)
curl -XPUT "${url}" --upload-file <FILE_NAME>

Python Implementation

Below is a python implementation of the approach to uploading files with the File Upload API.

#!/usr/bin/env python3

import requests


def request_presigned_url(token, file_path):
url = ""
payload = {"filename": file_path}
headers = {"Auth-Api-Token": token}
response = requests.request("POST", url, json=payload, headers=headers)
return response.json()

def upload_file(url, file_path):
response = requests.put(url, data=open(file_path, "r").read())
return response.status_code

presigned_url = request_presigned_url(TOKEN, FILE_PATH)

upload_status = upload_file(presigned_url["url"], FILE_PATH)


Powered by HelpDocs (opens in a new tab)