Datafiles are JSON files with entity, device, instrument or event data ready for bulk upload through this endpoing.

The /datafiles endpoint can upload and check the status of a file.

ENDPOINT

DESCRIPTION

POST /datafiles/create

Uploads a file with (bulk) entity, event or instrument information.

GET /datafiles/<unit21_id>

Retrieves details such as the current status of a datafile.

POST datafiles/<unit21_id>/mappings

Retrieves mappings of a datafile.

Create Datafile

Only one file at a time can be updated, with each file being up to 30 MB (megabytes). Please add a waiting time of 2 seconds between upload requests.

Use --form to specify the datafile and to specify the run_rules option which allows the user to specify whether to run rules after processing of the datafile is completed.

We support JSON only.

curl -X POST \
  'https://<API_ENDPOINT>/v1/datafiles/create' \
  -H 'Content-Type: multipart/form-data' \
  -H 'u21-key: <YOUR_API_KEY>' \
  --form '[email protected]' \
  --form 'run_rules=true'

Datafile Example

Below is an example of a datafile with a single user entity:

[
  {
    "general_data": {
      "entity_id": "Datafile-User1",
      "entity_type": "user",
      "entity_subtype": "payments",
      "status": "active"
    },
    "user_data": {
      "first_name": "Matthew",
      "middle_name": "Joseph",
      "last_name": "Baker",
      "day_of_birth": 14,
      "month_of_birth": 1,
      "year_of_birth": 1983,
      "gender": "male",
      "ssn": "733-99-5921"
    },
    "communication_data": {
      "email_addresses": [
        "[email protected]"
      ],
      "phone_numbers": [
        "+14159627132"
      ]
    },
    "custom_data": {
      "uploaded": "Via Datafile"
    }
  },
  {
    "general_data": {
      "entity_id": "Datafile-User2",
      "entity_type": "user",
      "entity_subtype": "payments",
      "status": "active"
    },
    "user_data": {
      "first_name": "Matt",
      "middle_name": "Joe",
      "last_name": "Baker",
      "day_of_birth": 14,
      "month_of_birth": 1,
      "year_of_birth": 1983,
      "gender": "male",
      "ssn": "733-99-5921"
    },
    "communication_data": {
      "email_addresses": [
        "[email protected]"
      ],
      "phone_numbers": [
        "+14159627132"
      ]
    },
    "custom_data": {
      "uploaded": "Via Datafile"
    }
  }
]
HTTP/1.1 200 OK
Content-Type: application/json
{
    "file_name": "Datafile.json",
    "unit21_id": 42399
}

If an identical data file has already been sent into the system, you will receive a 409 error code:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "error_code": "duplicate resource",
    "message": "Pre-existing datafile Datafile.json with unit21_id: 42399",
    "unit21_id": "42399"
}

If the file datafile is new, even if it has objects that already exist in the system, you will receive a successful response.

Get Datafile

The result of a GET is as follows:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "entity_count": 2,
    "event_count": 0,
    "file_name": "Datafile.json",
    "instrument_count": 0,
    "status": "PROCESS_SUCCESS",
    "unit21_id": 42399,
    "uploaded_at": "2021-10-23 23:39:08",
    "uploaded_by": "[email protected]"
}

The result of a failed GET is as follows:

HTTP/1.0 404 NOT FOUND
Content-Type: application/json
{
  "error_code": "invalid_action",
  "message": "Cannot find datafile specified by id <unit21_id>"
}

Datafile Mapping

To retrieve the mappings of a datafile, you can send a request that includes the Unit21 id of the datafile along with the offset as the results will be paginated.

The response will include 3 lists: a list of the entities, a list of events, and a list of instruments that were uploaded via the datafile specified by unit21_id.

Each list will be limited to maximum 500 items. The total number of items can be retrieved from get endpoint.

The mapping results are as follows:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "entity_list": [
        {
            "entity_id": "Datafile-User1",
            "unit21_id": 589254991
        },
        {
            "entity_id": "Datafile-User2",
            "unit21_id": 589254934
        }
    ],
    "event_list": [],
    "instrument_list": []
}

Please note that an empty response {} will be returned if the datafile is not yet processed.