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 and user-event rows per import: Entity CSV rows per import use the same plan table, then apply a hard ceiling of 20,000 (Growth/Enterprise/usage_based therefore max out at 20,000). Discover the effective number at runtime: GET /individual-organization/batch-upload-enabled → maxBulkEntityItemsPerImport. 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.

​
Concurrency (transactions and entities)

Pools are separate across organizations: transaction batches and entity batches do not share the 2-org cap. Inside one organization, only one of those types may run at a time, and at most one job may wait (queued). Transaction jobs stay running until queued rule evaluation finishes (when executeRules is true). If executeRules is false, the job completes after inserts. User-event imports are not subject to this mutex or slot pool.

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