Skip to main content

Upload Data Import

POST 
/api/v2/data-imports

Uploads mapped CSV data for import and kicks off background validation. Returns the data import ID and a tracked job log ID to poll for validation progress.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Authentication: Requires Bearer token.

Per-entity authorization: For the gated entity types (customers, warehouses, suppliers, sales_reps, categories) the user must hold the matching <entity>.import permission (e.g. customers.import). Other entity types are not gated here. The check resolves through the granular_permissions feature flag — it is a no-op while that flag is off. Returns 403 when the user lacks the required permission.

Request Body:

  • entity_type (required, string): Type of entity being imported (e.g. products, customers, warehouses, suppliers, sales_reps)
  • file_name (required, string, max:255): Original filename for display
  • column_mapping (required, array): Maps column positions to field names
  • mapped_rows (required, array, min:1): Array of row objects with mapped field values
  • metadata (nullable, array): Optional metadata

Request​

Responses​

Created