> ## Documentation Index > Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt > Use this file to discover all available pages before exploring further. # Bulk imports > CSV batch imports with saved column mappings (transactions, entities, user events) — via the gu1 batch import API for high-volume data loading. ## 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: | 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](/en/api-reference/transactions/create-batch). | | **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](/en/api-reference/bulk-imports/import-entities) (CSV multipart; same wizard as the hub). | | **Entities — CSV multipart (API)** | [POST /batch-import/import/entities](/en/api-reference/bulk-imports/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](#limits-by-plan) (hard cap 100,000 rows/file before processing) | | **Entities (CSV / hub)** | `POST /batch-import/import/entities` | **1** | By [plan](#limits-by-plan); optional server cap via `BULK_AUTOMATIC_ENTITY_MAX_ITEMS` | | **User events** | `POST /batch-import/import/user-events` | **1** | By [plan](#limits-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 | 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](/en/api-reference/transactions/create-batch). ### 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` | Details: [Import entities (CSV)](/en/api-reference/bulk-imports/import-entities). ### 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](/en/api-reference/bulk-imports/batch-import-failure-codes). | Resource | CSV | JSON | | ------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Transactions | `GET /batch-import/transaction-jobs/{jobId}/failures.csv` | [GET …/failures](/en/api-reference/bulk-imports/get-transaction-batch-failures) | | User events | `GET /batch-import/user-event-jobs/{jobId}/failures.csv` | [GET …/failures](/en/api-reference/bulk-imports/get-user-event-batch-failures) | | Entities | `GET /batch-import/entity-jobs/{jobId}/failures.csv` | [GET …/failures](/en/api-reference/bulk-imports/get-entity-batch-failures) (includes `skips[]` for duplicate taxId) | **Typical flow:** upload → poll [Get batch job status](/en/api-reference/bulk-imports/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. ### Related documentation * **[Endpoints overview](/en/api-reference/bulk-imports/api-reference)** — 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](/en/api-reference/transactions/create-batch) — multipart upload and limits for transaction files.