Skip to main content

​
Overview

Bulk imports let you upload CSV files mapped to Gu1 fields using saved mappings (mappingId). The dashboard hub (Bulk imports) uses the same API routes as integrations. Base path: all routes below are prefixed with /batch-import (for example GET https://api.gu1.ai/batch-import/mappings).

​
Authentication

Use the same Bearer API key or session as the rest of the API. Requests are organization-scoped; mappingId values belong to the current organization only.

​
Naming: mappingId (not mapperId)

Multipart imports expect the form field mappingId, the UUID returned when you list or create mappings (GET / POST /batch-import/mappings). There is no mapperId field.

​
“Platform” vs custom CSV

There is no single type: custom | platform parameter. Behavior depends on the route and whether you send a mapping:

​
Limits (all bulk imports)

Integrators should assume one CSV/file field per request for entity and user-event imports unless noted. Transaction upload accepts up to 5 files in one multipart request.

​
Limits by plan

Applies to transaction rows per file, entity CSV rows per import, and user-event rows per import (same numbers in the API): When a file exceeds the limit, the API returns 400 with code TOO_MANY_ITEMS (entities, user events) or a plan-limit error message (transactions). Discover limits at runtime: GET /individual-organization/batch-upload-enabled returns plan, maxTransactionsPerFile, maxBulkEntityItemsPerImport, maxUserEventRowsPerFile, and per-plan maps. Transaction body size (JSON batch): max 50 MB per single batch request; 150 MB for multi-file background upload. See Create batch transactions.

​
Entity import: manual vs automatic

Same background job queue; mode is set with importMode (JSON) or entityImportMode (CSV multipart). Details: Import entities (CSV).

​
Row failures and stable codes

Each failed row includes a stable code and human message. Download CSV or JSON by job type. Full catalog: Batch import failure codes. Typical flow: upload → poll Get batch job status until status is terminal (completed, failed, cancelled, or interrupted) → fetch failures (CSV/JSON or ?include=failures) if failed > 0 or inspect jobFailure when the whole job aborted.
CSV breaking change (2026-06-04): failure CSVs now include a code column. Parsers that assumed exactly two columns must read by header name, not column index.
  • Endpoints overview — table of all routes; each endpoint below has its own page with the GET/POST badge in the sidebar (same pattern as the rest of the API docs).
  • Create batch transactions — multipart upload and limits for transaction files.