Import items in bulk

This endpoint lets you upload a CSV file containing people, events, objects, or relationships. It provides a handy way of adding and updating them in bulk. Uploading people, objects, or relationships is like performing an identify call for each row in your CSV; uploading events is like performing a track call.

You'll need to provide us the public URL of your CSV as a part of this operation. We recommend that you host your CSVs from short-lived URLs. Ideally, your URLs will expire 2 hours after you initiate an import so that your customers' information doesn't remain publicly available after you've uploaded it to us.

Check out the CSV requirements based on what you're importing: people, events, and objects or relationships.

This endpoint performs some basic validation on the request and then queues the import for processing. The import happens in multiple stages after your request, and may even fail. You'll need to lookup the status of the import to check on its progress.

Records in your CSV might result in errors or warnings during the import. We make the errors and warnings available in CSV files that you can download via our export endpoints. Lookup your import to get download URLs for error and warning reports.

post/v1/imports

Request body

Example request

{
  "import": {
    "object_type_id": "1"
  }
}

Response

Returns an import payload.

Example response

{
  "import": {
    "id": 30,
    "name": "account-object-import",
    "description": "importing accounts",
    "created_at": 1706081641,
    "updated_at": 1706081645,
    "rows_to_import": 3,
    "rows_imported": 3,
    "state": "imported",
    "type": "object",
    "data_to_process": "all",
    "people_to_process": "all",
    "object_type_id": 1,
    "error": "possible error - The specified Object Type does not exist."
  }
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.