User Upload API

Bulk API to insert User records. This API endpoint accepts POST requests with JSON data containing a list of User records wrapped in a dictionary.

POST /v1/users

{
  "data": [user_1, user_2, user_3]
}

If a record with the same user_id already exists in the dataset, the existing record will be replaced (no partial update is allowed at this time). We recommend limiting your calls to around 100 records at a time to avoid memory issues or timeout risks.

Schema validation

This API validates the inserted records against the API schema. Any schema error will cause the whole request to fail (status_code=422), and none of the records will be inserted. As long as the request passes the schema validation, the API will return status_code=200, but you should still check if there is any error occurring with individual records.

{
    "errors": true,
    "data": [
        "data.0.user_id is invalid. The attribute was expected to be a `string`"
    ]
}

Response Format

The API will return a JSON object with a task_id that can be used to retrieve.

Example Successful Response

{
  "data": {
    "task_id": "{task_id}"
  }
}

To check the exact response body of this task_id, make a GET request to the following endpoint:

GET /v1/users/_status/{task_id}

Replace {task_id} with the task_id returned from the response.

{
  "data": [
    {
      "user_id": "user_1234",
      "name": "John Doe",
      "age": 33,
      "gender": "M",
      "city": "Mountain View",
      "state": "California",
      "country": "US",
      "group_id": "Northwind Corp",
      "description": "Engineer from Northwind Corp",
      "custom_attributes": {
        "acquisition_channel": "Facebook Campaign 2020",
        "declared_interests": [
          "Drama",
          "Romance"
        ]
      }
    }
  ]
}

{
  "message": "success"
}