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.
There is no single type: custom | platform parameter. Behavior depends on the route and whether you send a mapping:
| Scenario | How it works |
|---|
| Transactions — native file format | POST /transactions/batch/upload without mappingId or columnMapping: server parses CSV / Excel / JSON with the built-in parser. See Create batch transactions. |
| Transactions — saved mapping | Same upload endpoint with mappingId, or columnMapping as a JSON string (CSV only). Also available as POST /batch-import/import/transactions. |
| Entities — dashboard “Entities” tab | POST /batch-import/import/entities (CSV multipart; same wizard as the hub). |
| Entities — CSV multipart (API) | POST /batch-import/import/entities (default manual; automatic when explicit). |
| Entities — arbitrary CSV columns | POST /batch-import/import/entities with file + mappingId. |
| User events | POST /batch-import/import/user-events with file + mappingId (target user_event). |
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.
| Import type | Endpoint(s) | Files per request | Max rows per file / request |
|---|
| Transactions | POST /transactions/batch/upload, POST /batch-import/import/transactions | Up to 5 | By plan (hard cap 100,000 rows/file before processing) |
| Entities (CSV / hub) | POST /batch-import/import/entities | 1 | By plan; optional server cap via BULK_AUTOMATIC_ENTITY_MAX_ITEMS |
| User events | POST /batch-import/import/user-events | 1 | By plan; optional server cap via USER_EVENT_BATCH_IMPORT_MAX_ROWS |
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):
| Plan | Max rows per file / import |
|---|
| Freemium | 4,000 |
| Startup | 12,000 |
| Growth | 30,000 |
| Enterprise | 100,000 |
| Usage based | 100,000 |
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).
| Manual (manual) | Automatic (automatic) |
|---|
| Basic data by tax ID (Nosis/CPF / Chile providers) | No | Yes |
| Display name | suggested_name / suggestedName required every row | Recommended |
| Country (ISO2) | Required — batch country and/or CSV country_code (row overrides batch) | Same (automatic: AR, BR, CL only) |
| Enrichments | Optional (autoExecuteIntegrations / CSV columns) | Defaults to all active; optional pick list |
Shareholder depth | No | Yes (0–5) |
| Countries | Any valid platform ISO2 | AR, BR, CL |
| Default endpoint | POST /batch-import/import/entities | POST /batch-import/import/entities with entityImportMode=automatic |
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.
| Resource | CSV | JSON |
|---|
| Transactions | GET /batch-import/transaction-jobs/{jobId}/failures.csv | GET …/failures |
| User events | GET /batch-import/user-event-jobs/{jobId}/failures.csv | GET …/failures |
| Entities | GET /batch-import/entity-jobs/{jobId}/failures.csv | GET …/failures (includes skips[] for duplicate taxId) |
completed / failed → fetch failures endpoint 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.
