List Upload API


This API allows users to upload a file to Versium Reach, enabling the integration of user data into the platform.


API End point:

Http method: POST

Content-Type: multipart/form-data

Configuration Parameters







A CSV file

 The file to be uploaded



1 or 0

A boolean indicating whether the uploaded csv file contains a header in the first row.



JSON string

See below for details.

The header_map parameter

The header_map parameter defines the mapping of field types to the corresponding 0-based column indexes in the file. Each field type is associated with an array of integers representing the columns of the file that correspond to that field type. Field indexes must be unique across field types. If passed, the structure of the header_map parameter must be a JSON object.


  "Fullname": [0], 
  "First": [1],
  "Last": [2],
  "City": [3],
  "State": [4],
  "Email": [5, 6],
  "Phone": [7, 8, 9]

Response Structure

The API responds with a JSON object containing detailed information about the uploaded file and its processing status. If you wish to use this list with one of the job APIs, you will need the id of the list.

The response will also contain the following:

  • id (integer): A unique identifier for the uploaded file. This is the list id value that will be supplied to the job APIs.
  • guid (string): A globally unique identifier associated with the file.
  • name (string): The name of the uploaded file.
  • records (integer): The total number of records in the uploaded file.
  • size (integer): The size of the uploaded file in bytes.
  • input_field_fill_rate (object): A mapping of field names to the number of non-empty values for each field.
  • column_count (integer): The total number of columns in the file.
  • file_ready (boolean): Indicates whether the file is ready for use in the system.
    "versium": {
        "version": "2.0",
        "query_id": "9dc4828868e938d263a77fd1a7a63623",
        "query_time": 0.18544507026672363,
        "results": {
            "id": 213,
            "guid": "8c9aa0de-bad2-456b-9b18-639e24398b73",
            "name": "MyFileWithDupes.txt",
            "campaign_id": null,
            "created_at": "2024-04-09T19:17:00.000000Z",
            "finished_at": null,
            "header_map": {...},
            "has_header": true,
            "delimiter_type": 2,
            "records": 100000,
            "size": 12773898,
            "input_field_fill_rate": {
                "fullname": 28384,
                "first": 99997,
                "last": 99984,
                "email": 100000,
                "phone": 71414,
                "address": 9303,
                "city": 9754,
                "state": 9754,
                "zip": 73121
            "column_count": 16,
            "append_field_fill_rate": null,
            "file_ready": true,
            "source": "API",
            "to_be_deleted": null,
            "last_download_date": null,
            "jobs": {
                "withTimestamps": false