Please note: This API will not be supported from 1st August 2023. We highly recommend to use the PUT Records API instead.


This API is designed to allow upload of a single data file directly into CustomerGauge for immediate processing (Mail queue) and email sending.

Depending on active rules and data types (usually order_date field) customer emails will be sent immediately.

This API will load emails into the "Mail queue", and may start immediate processing. Make sure you test this before bulk uploads! 

Good to know

Maximum file size:

Please do not upload files larger than 2MB.

Maximum number of records:

Please do not upload files with more than 2,000 records.

Upload interval / frequency:

Multiple upload calls made in quick succession will get queued, and periodically retried, but to obtain optimum performance we recommend allowing the previous upload to finish before attempting the next one. (Uploads can take anywhere between a few seconds and several minutes depending on the size and complexity of data.)

Uploadable file types:

We accept CSV, XLS(X), and XML files (note: no JSON files).

API response format:

Our APIs return data in either JSON or XML format (depending on request by .json or .xml).

Required fields & field validations:

Based on your system's configuration, some fields may be required, or need to be in a specific format.

Contact your Customer Success Manager when in doubt.

Usually, the following validations apply:

  • Datetime is required and in YYYY-mm-dd H:i:s format.
  • Email is required for the upload to be valid

CSV and XLS(X) - Column positions:

For CSV and XLS(X) files, the order/position of columns is important. You'll need to ensure that each column is present and in the right place in your file, even if you don't have data against it. Please refer to the sample file section below to find out which columns need to be in which order.

About this API

Resource information

Response formats
JSON (default), XML
HTTP Method
Response family
Authorization: api_key XXXXX

Resource URL

Europe Production Server:

US Production Server:

Australia Production Server:

How to call


Automatically provided when POST-ing a file through HTTP protocol.

Sample file

As many clients have different data fields, you can pick up a sample copy from your system.

1. Go to Data → Imports in the menu, and click the link to the legacy import screen.

2. Click on "Upload File"

3. Click on "Download Data Structure", followed by Transactional (CSV), Transactional (XLS), or Transactional (XML).

4. Use the same structure as this sample file when calling our POST File/Transactional API.

Upload File Example Request

Post your file by calling our API as if posted from a form. 
curl -H "Authorization: api_key XXXXX" -F "file=@LOCAL_LOCATION/file_name.xml" ""

Example Result

Data states if successful or not. Message reported on successful operation:

    "Data": {
        "id": "1"

Message reported on failed operation:

    "Error": {
        "Message": "This upload has already been processed",
        "Code": 400103