This endpoint lets you upload a file containing people, events, objects, relationships, or geofences. 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. Uploading geofences adds or updates them in a geofence set, the same way an import in the UI does. Geofence imports are available on Premium and Enterprise plans.

You'll need to provide us the public URL of your file as a part of this operation. We recommend that you host your files 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 file requirements based on what you're importing: people, events, objects or relationships, and geofences.

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 file 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.

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

{
  "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."
  }
}