Skip to content

Upload API

This article describes the workflow for the Upload API — the synchronous REST interface for submitting data and retrieving processed results.

Refer to our API reference documentation for endpoint details and schema definitions.

Workflow in steps

The Upload API uses the OAuth 2.0 Client Credentials flow for authentication. Follow the steps below to integrate:

  1. Generate a bearer token. Ensure:

    • your <client_secret> is URL-encoded — use urlencoder.org if needed
    • the <client_id>:<url_encoded_client_secret> string is base64-encoded
    • the content-type is x-www-form-urlencoded
    • grant_type is client_credentials

    • scope is platform_upload_api

      Encoding manually?

      Use base64encode.org to encode or decode your <ClientID>:<URL_Encoded_ClientSecret> string.

      5471E010-DDEE-4C98-FF8F-08DB2245E373:7rg6Gt+hUiobtXI9Jb37z2vtrhw1CEgDkwFZcMbN5Yc=

      NTQ3MUUwMTAtRERFRS00Qzk4LUZGOEYtMDhEQjIyNDVFMzczOjdyZzZHdCtoVWlvYnRYSTlKYjM3ejJ2dHJodzFDRWdEa3dGWmNNYk41WWM9

      Basic NTQ3MUUwMTAtRERFRS00Qzk4LUZGOEYtMDhEQjIyNDVFMzczOjdyZzZHdCtoVWlvYnRYSTlKYjM3ejJ2dHJodzFDRWdEa3dGWmNNYk41WWM9

  2. Upload your data to the /UploadData endpoint using the token for Bearer authorization. Ensure:

    • all required fields are present
    • the Data field columns are in the correct order

  3. Check processing status using the /GetResults endpoint with dataKey=status. Ensure:

    • the correct bearer token is used for authorization
    • the processing token from step 2 is correct

  4. If status is not completedsuccessfully, set dataKey=feedback and submit to retrieve error details.

    • Resolve any validation errors in your data
    • Return to step 2, keep the Name the same, and set Overwrite to true

  5. If status is completedsuccessfully, set dataKey to the result type you want and retrieve your output.

Payload

Request payload

The request payload differs between the /UploadData and /GetResults endpoints.

For Upload Data

Download example files

Download example files for Data CSV and Event Data CSV here.

See our API reference documentation for full details.

Schema
Namestring Required

A name for this submission. Used to identify the dataset and to overwrite it if resubmitting.

Datastring Required

The primary dataset in CSV format. Notes:

  • Values must be comma-separated.
  • Columns must appear in the order shown in the schema below.
  • Column headers may be omitted; the defined column order is assumed.
  • Multiple rows may be submitted in a single request.
  • Required columns must always be present. Optional columns may be omitted if no columns follow them.


Column Name
(+ required)		 Format Description
Reference+ Text A free-text identifier for the record. Typically a user ID or name.
StartDate+ Date (DD/MM/YYYY) The record start date.
StartTime+ Time (hh:mm) The record start time.
EndDate+ Date (DD/MM/YYYY) The record end date.
EndTime+ Time (hh:mm) The record end time.

EventDatastring

An optional secondary dataset for event-level records, in CSV format. Notes:

  • Values must be comma-separated.
  • Columns must appear in the order shown in the schema below.
  • Multiple rows may be submitted in a single request.


Column Name
(+ required)		 Format Description
Reference+ Text A free-text identifier for the event record. Typically a user ID or name.
EventStartDate+ Date (DD/MM/YYYY) The event start date.
EventStartTime+ Time (hh:mm) The event start time.
EventEndDate+ Date (DD/MM/YYYY) The event end date.
EventEndTime+ Time (hh:mm) The event end time.
Description+ Text A free-text description of the event.
TimeReference+ Number (0–2) Timezone context for the event times. Send
  • 0 for UTC
  • 1 for Base (home location)
  • 2 for Local (event location)

Usernamestring

Your Client ID. Obtainable from the Platform web app.

Keystring Required

Your API key. Obtainable from the Platform web app.

Overwriteboolean

Set to true to overwrite an existing submission with the same Name.

Example
{
  "Name": "Sample submission 1",
  "Data": "Reference,StartDate,StartTime,EndDate,EndTime\r\nUser1,12/05/2024,09:00,12/05/2024,17:00",
  "EventData": "Reference,EventStartDate,EventStartTime,EventEndDate,EventEndTime,Description,TimeReference\r\nUser1,12/05/2024,09:05,12/05/2024,09:30,Meeting,0",
  "Username": "5471E010-DDEE-4C98-FF8F-08DB2245E372",
  "Key": "90CBF21C-33D4-4C32-944A-22A0C416DF89",
  "Overwrite": "false"
}

For Get Results

No request body is required. Pass the following query parameters:

Schema
Parameter Description
token The processing token returned by the /UploadData endpoint
dataKey The type of result to retrieve. Send one value at a time: status, feedback, or tableofresultids. Check status first and wait for completedsuccessfully before querying for output.
key Your API key

Response payload

For Upload Data

"9e529abf-6b2f-4a17-92de-d1cfc85976db"

The response is a processing token string. Pass this to /GetResults to retrieve output.

For Get Results

"completedsuccessfully"

"Data import and processing was successful"

"137267,137268"