> ## 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.
# Import entities (CSV)
> Upload a CSV and enqueue bulk entity import — platform format without mappingId or custom columns with mappingId. Manual by default; automatic when explicit.
## Endpoint
```
POST https://api.gu1.ai/batch-import/import/entities
```
## Overview
**Content-Type:** `multipart/form-data`.
Enqueues the same bulk job as the dashboard **Bulk imports** hub. Requires **`entities:bulk_import`** and org **bulk automatic entity import** enabled. **`202`** response includes **`jobId`** and effective **`importMode`**.
## Authentication
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Import Modes (`entityImportMode`)
| Mode | When | Behavior |
| --------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`manual`** | **Default** when the field is omitted | **Minimal** entity from `taxId` + **`suggested_name`** (required). **No** country basic-data pipeline (Nosis/CPF). **Optional** selected enrichments via form `autoExecuteIntegrations` and/or per-row CSV columns. **No** shareholder `depth`. **Country:** any valid platform ISO2 (`country_code` per row takes priority). |
| **`automatic`** | Send `entityImportMode=automatic` | Basic data by tax ID (**AR**, **BR**, or **CL**) + enrichments (defaults to all active when `autoExecuteIntegrations` omitted) + optional `depth` / shareholders. |
Legacy values `manual_no_enrichment` and `automatic_enriched` are still accepted on input and normalized to **`manual`** / **`automatic`**. Responses use the canonical names.
### Default When Sending Only the CSV
```bash theme={null}
curl -X POST 'https://api.gu1.ai/batch-import/import/entities' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'file=@bulk-entities-template.csv'
```
→ **`importMode`: `manual`** — minimal entity, **no enrichments** unless you add them explicitly.
### Manual with Selected Enrichments
Same semantics as the dashboard **Manual** mode:
```bash theme={null}
curl -X POST 'https://api.gu1.ai/batch-import/import/entities' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'file=@bulk-entities-template.csv' \
-F 'entityImportMode=manual' \
-F 'autoExecuteIntegrations={"executeAllActiveEnrichments":false,"enrichments":["nosis_enrichment"]}' \
-F 'riskMatrixCompanyId=YOUR_MATRIX_UUID'
```
Optional **`monitoring`** JSON (main entity only in manual mode).
### Automatic Mode (Explicit)
```bash theme={null}
curl -X POST 'https://api.gu1.ai/batch-import/import/entities' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'file=@bulk-entities-template.csv' \
-F 'entityImportMode=automatic'
```
Omitting **`autoExecuteIntegrations`** in automatic mode → all active enrichments for the org.
With **`depth` > 0**, send **`autoExecuteIntegrationsShareholders`** (JSON) for shareholders.
### Manual without Post-Create Rules
```bash theme={null}
-F 'entityImportMode=manual' \
-F 'skipRulesExecution=true'
```
(You can omit `entityImportMode` — manual is already the default.)
## Platform CSV (no `mappingId`)
Minimum headers: **`tax_id`**, **`type`**. Recommended: **`suggested_name`** (required in manual mode). See [Country (ISO2)](#country-iso2--always-required) below for **`country_code`**.
### Country (ISO2) — Always Required
Every entity row needs a country to create the record (**manual and automatic**). Provide it in **one or both** places:
| Source | When to use |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Batch form field** `country` | Step 2 in the hub, or multipart field in the API. **Required** for simple CSV (only `tax_id` + `type`). **Required** for any row that omits `country_code`. |
| **CSV column** `country_code` (alias `country`) | Per row. **Overrides** batch `country` when present. |
**Priority:** `country_code` on the row → batch `country`.
**If neither is set for a row**, the import fails with `missing country` before the job runs.
| Mode | Allowed countries |
| --------------------------- | -------------------------------------------- |
| **Automatic** (`automatic`) | **AR**, **BR**, **CL** (basic-data pipeline) |
| **Manual** (`manual`) | Any valid platform ISO2 |
**Examples:**
* Simple CSV, all rows Argentina → headers `tax_id,type` + form `country=AR`.
* Advanced CSV, mixed countries → include `country_code` on each row (form `country` optional fallback).
* Advanced CSV, single country → either all rows with `country_code=AR` **or** form `country=AR` without the column.
Reference templates — **download** (fixed demo tax IDs; replace before production import) or generate fresh IDs from the dashboard hub (**Entities** → bulk import):
* [**bulk-entities-template-automatic.csv**](/files/bulk-imports/bulk-entities-template-automatic.csv) — use with **`entityImportMode=automatic`**. AR/BR/CL demo rows, `depth`, `create_relationships`, `execute_all_active_enrichments`.
* [**bulk-entities-template-manual.csv**](/files/bulk-imports/bulk-entities-template-manual.csv) — use with **`entityImportMode=manual`** (default). AR/MX/BR demo rows, **`suggested_name` filled**, no `depth` columns (any ISO2).
Canonical source (keep in sync when columns change): `apps/web/src/lib/bulk-automatic-entity-import-parse.ts`.
Automatic example (truncated):
```csv theme={null}
tax_id,type,country_code,suggested_name,...,execute_all_active_enrichments,...,depth,status,segment_tag
20123456789,company,AR,Acme Argentina SA,...,true,...,0,under_review,retail
12345678000190,company,BR,Loja Brasil Ltda,...,true,...,1,under_review,wholesale
```
Manual example (truncated):
```csv theme={null}
tax_id,type,country_code,suggested_name,...,status,segment_tag
20123456789,company,AR,Empresa Manual AR SA,...,under_review,retail
XAXX010101000,company,MX,Empresa México Demo SA,...,active,latam
```
Legacy single-file name `bulk-entities-template.csv` is no longer used by the hub; pick the template matching your **`entityImportMode`**.
### Column Reference (Platform CSV)
Header names are **case-insensitive**; spaces become `_` (e.g. `country code` → `country_code`). Aliases in parentheses.
| CSV column | Aliases | API / entity field | Notes |
| ------------------------------------ | --------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`tax_id`** | `taxId` | `taxId` | **Required.** Normalized per country (e.g. CUIT formatting for AR). |
| **`type`** | `tipo` | `type` | **Required.** `person` / `company` (also `persona`, `empresa`, `pf`, `pj`). |
| **`country_code`** | `country` | `country` | ISO2 **per row**. **Overrides** batch form `country`. Column is **optional in the CSV** when batch `country` is sent (simple CSV) or when every row includes `country_code`. **Country is always required** — row column and/or batch field. |
| **`suggested_name`** | `name`, `nombre` | `suggestedName` | Display name. **Required in manual mode** on every row. Recommended in automatic. |
| **`gender`** | — | `gender` | Passed to entity creation (`customData`). Enum: `M`, `F`, `male`, `female`, `other`, `unknown`. Use **`other`** for non-binary. See [Create entity — Person](/en/api-reference/entities/create#person-entity). |
| **`external_id`** | `externalId` | `externalId` | External reference on the entity. |
| **`email`** | — | `email` | Contact email on the entity. |
| **`phone`** | — | `phone` | Contact phone on the entity. |
| **`registration_date`** | — | `registrationDate` | Registration date (ISO string). |
| **`risk_matrix_id`** | — | `riskMatrixId` | UUID of a risk matrix for **this row**, or empty / `null` to clear. Invalid values are skipped. Overrides batch `riskMatrixPersonId` / `riskMatrixCompanyId` when set. |
| **`execute_all_active_enrichments`** | — | `autoExecuteIntegrations.executeAllActiveEnrichments` | `true` / `false` / `1` / `0`. Row-level enrichments apply when this column, **`enrichments`**, or **`enrichment_group_refs`** is present. |
| **`enrichments`** | — | `autoExecuteIntegrations.enrichments` | Comma- or semicolon-separated [marketplace provider codes](/en/api-reference/integrations/provider-codes). Merged with batch form `autoExecuteIntegrations` when the row sets enrichment columns. |
| **`enrichment_group_refs`** | — | `autoExecuteIntegrations.enrichmentGroupRefs` | Comma-separated enrichment group slugs from the marketplace. |
| **`omit_enrichments`** | `exclude_enrichments` | `autoExecuteIntegrations.excludeEnrichments` | Provider codes to **omit** from the final resolved set. Works with **`execute_all_active_enrichments=true`** (all active minus these). When this is the **only** enrichment column on the row, it **merges** onto the batch config instead of replacing it. |
| **`create_relationships`** | — | `createRelationships` | `true` / `false`. **Automatic mode only** (ignored in manual). |
| **`depth`** | — | `depth` | Integer **0–5**. Shareholder/relationship expansion. **Automatic mode only** (stripped in manual). Batch form `depth` applies when the row omits this column. |
| **`related_tax_id`** | — | `relationships[].relatedTaxId` | Existing counterpart by tax ID. **Exactly one** of `related_tax_id` / `related_external_id` / `related_entity_id` per row. |
| **`related_external_id`** | — | `relationships[].relatedExternalId` | Counterpart by `externalId`. |
| **`related_entity_id`** | — | `relationships[].relatedEntityId` | Counterpart by UUID. |
| **`relationship_type`** | — | `relationships[].relationshipType` | Defaults to `shareholder` when a counterpart is set. Graph enum. |
| **`relationship_role`** | — | `relationships[].role` | Role in `metadata.roles` (e.g. `SOCIO`). |
| **`relationship_as_source`** | — | `relationships[].asSource` | Default `true`: the created row is **source** and the counterpart (`related_*`) is **target**. With `relationship_type=shareholder`, the row is a shareholder of that counterpart. `false` reverses the direction. |
| **`status`** | — | `status` | One of: `active`, `inactive`, `blocked`, `under_review`, `suspended`, `pending_verification`, `expired`, `deleted`, `rejected`. |
| **`attributes.`** | — | **`attributes`** | Nested business data (same dot notation as native transaction CSV). E.g. `attributes.segment_tag`, `attributes.tags.tier`. |
| **`entityData.`** | — | **`entityData.{person\|company}`** | KYC/KYB profile fields. Without `person`/`company` in the header, the row **`type`** selects the bucket (`person` → `entityData.person.*`, `company` → `entityData.company.*`). E.g. `entityData.income`, `entityData.tradeName`. |
| **`entityData.person.`** | — | **`entityData.person`** | Explicit person path. |
| **`entityData.company.`** | — | **`entityData.company`** | Explicit company path. |
| **`metadata.`** | — | **`attributes`** (legacy) | Deprecated; merged into `attributes`. Prefer `attributes.*`. |
| **Unprefixed column** | — | **`attributes`** | Backward compatible: `segment_tag` → `attributes.segment_tag`. |
**Same entity, multiple links (CSV):** platform CSV supports **one** relationship per row. If the same person/company appears on several rows with different `related_*`, Gu1 **does not recreate** the entity (duplicate `tax_id` skip) but **still applies** that row’s link. If the edge (source → target + type) already exists, that link is skipped (idempotent). API/JSON alternative: a single create with up to 10 items in `relationships[]`.
**Removed (2026-06-04):** CSV columns **`execute_all_active_checks`** and **`checks`** are no longer part of the import contract. Use **`enrichments`**, **`enrichment_group_refs`**, and **`execute_all_active_enrichments`** instead. See [Changelog](/en/changelog).
**Dot notation:** same as native transaction CSV — dotted headers build nested objects. Enrichments may overwrite `entityData`; CSV values are re-applied at the end (CSV wins on conflicts).
**What goes to `attributes`:** `attributes.*`, legacy `metadata.*`, or unprefixed columns. Batch-level form field **`attributes`** (JSON) is merged with per-row attributes (row wins on key collision).
**Simple CSV** (only `tax_id` + `type`): send batch form field **`country`** (ISO2) — required. No `country_code` column needed.
**Custom CSV** (non-platform headers): use a saved **`mappingId`** — column mapping is defined in the dashboard, not by this table.
* Per-row enrichment columns apply in **both** modes when set on the row; **`depth`** / shareholders **only** in **`automatic`**.
### Related-Entity Enrichments per Row (Platform CSV)
Optional — **`automatic`** mode only. Prefix **`relationship_`** (plural alias **`relationships_`**).
| Column | Description |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `relationship_execute_all_active_enrichments` | `true` = all active enrichments on shareholders/related entities; `false` = basic data only. **Replaces** the batch policy (`childEnrichmentPolicy`) for that row. |
| `relationship_enrichments_company` | Provider codes for company-type children (comma or semicolon separated) |
| `relationship_enrichments_person` | Provider codes for person-type children |
| `relationship_enrichment_group_refs` | Marketplace groups (optional) |
| `relationship_omit_enrichments` | Alias of `relationship_exclude_enrichments`. Codes to omit from the final set (also with `execute_all_active=true`). When this is the **only** `relationship_*` column on the row, it **merges** onto the batch policy instead of replacing it. |
| `relationship_exclude_enrichments` | Same as `relationship_omit_enrichments` (legacy name). |
**Custom batch policies (e.g. Paytime):** omit `relationship_execute_all_active_enrichments` from the CSV if you want step-2 form policy to apply. Use `relationship_omit_enrichments` per row for one-off exceptions only.
Example: batch all-active on shareholders except global sanctions on children:
```csv theme={null}
tax_id,type,country_code,depth,relationship_omit_enrichments
67250861000107,company,BR,1,global_gueno_sanctions_enrichment
```
## Custom CSV
Non-platform column layout → **`mappingId`** required (`entity_person` / `entity_company` / `entity_mixed` mapping).
## Form Fields
| Field | Required | Description |
| ------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file` | Yes | CSV file |
| `mappingId` | Conditional | Custom columns. Optional for platform format. |
| `entityImportMode` | No | **`manual`** (default) or **`automatic`** |
| `country` | **Conditional (required in practice)** | Batch ISO2. **Required** when CSV has no `country_code` on a row (typical simple CSV). Optional fallback when every row includes `country_code`. |
| `riskMatrixPersonId` | No | UUID — both modes |
| `riskMatrixCompanyId` | No | UUID — both modes |
| `skipRulesExecution` | No | `true` / `false` (default `false`) |
| `stopOnFirstError` | No | `true` / `false` |
| `autoExecuteIntegrations` | No | JSON — manual: optional selected enrichments; automatic: defaults to all active when omitted |
| `autoExecuteIntegrationsShareholders` | No | JSON at batch level — **automatic mode only** + `depth` > 0. Per row: `relationship_*` CSV columns or field in JSON bulk. |
| `childEnrichmentPolicy` | No | **`all_active`** (default), **`by_root_type`**, or **`basic_only`** — automatic + `depth` > 0. See [Child enrichments & monitoring](#child-enrichments--monitoring). |
| `monitoringApplyToRelationships` | No | `true` / `false` — when `false`, `monitoring` applies to main entities only (no `monitoring.relationships`). Default **`true`** when `depth` > 0 if omitted. |
| `depth` | No | 0–5 — **automatic mode only** |
| `isClient` | No | `true` / `false` |
| `status` | No | Entity status literal (batch) |
| `attributes` | No | JSON (batch) |
| `nationality` | No | ISO2 |
| `monitoring` | No | JSON — both modes (relationships key: automatic + `depth` > 0 only) |
| `reportRecipientEmails` | No | JSON array |
| `emailLocale` | No | `en` / `es` / `pt` |
## Success Response
```json theme={null}
{
"success": true,
"jobId": "bulk-entity-…",
"importMode": "manual",
"totalItems": 42,
"message": "Bulk import queued"
}
```
## Child Enrichments & Monitoring
**Automatic mode** with **`depth` > 0** creates shareholders (company roots) or related entities (person roots). Two batch fields control how enrichments and watchlist monitoring apply to those children:
| `childEnrichmentPolicy` | Main entity | Company root → shareholders | Person root → related entities |
| -------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **`all_active`** (default) | As configured | All active enrichments for each child type (same as before) | Same |
| **`by_root_type`** | As configured | All active enrichments **except** `global_gueno_sanctions_enrichment` (check-only / no watchlist on children) | **Basic data only** from the root provider snapshot (no child enrichment pipeline) |
| **`basic_only`** | As configured | Basic data only | Basic data only |
**`monitoringApplyToRelationships`:** when **`false`**, the `monitoring` JSON applies to **main entities only** (`monitoring.main`); related entities are not added to watchlists even if enrichments run on them. Recommended **`false`** with **`by_root_type`** when the main entity should enter sanctions monitoring but children should not.
Example (mixed company + person CSV, depth 1, main watchlist only, differentiated children):
```bash theme={null}
-F 'entityImportMode=automatic' \
-F 'depth=1' \
-F 'childEnrichmentPolicy=by_root_type' \
-F 'monitoringApplyToRelationships=false' \
-F 'monitoring={"main":{"global_gueno_sanctions_enrichment":{"watchlist":true}}}'
```
Per-row **`autoExecuteIntegrationsShareholders`** in JSON bulk (`POST /entities/bulk/automatic`) or **`relationship_*` CSV columns** still override the batch policy for that item.
## Manual vs. Automatic (Same Job Queue)
| | **Manual** | **Automatic** |
| -------------------------------- | ------------------------------------------------------------------- | --------------------------------------------- |
| Basic data by tax ID (Nosis/CPF) | **No** | **Yes** |
| **`suggested_name`** | **Required** every row | Recommended |
| **Country (ISO2)** | **Required** — batch `country` and/or CSV `country_code` (row wins) | Same (automatic: **AR**, **BR**, **CL** only) |
| Enrichments | Optional (`autoExecuteIntegrations` / CSV row) | Default all active; optional pick list |
| Risk matrices | Yes | Yes |
| Shareholder `depth` | **No** | Yes (0–5) |
| Countries | **Any valid ISO2** | **AR**, **BR**, **CL** |
## Limits
| | Value |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Files per request** | **1** CSV (`file` field) |
| **Max rows per import** | By organization plan (same table as [Bulk imports overview — Limits by plan](/en/api-reference/bulk-imports/overview#limits-by-plan)): Freemium **4,000** → Enterprise / Usage based **100,000** |
| **Server cap (optional)** | `BULK_AUTOMATIC_ENTITY_MAX_ITEMS` may lower the plan limit on this endpoint |
| **Over limit** | **`400`** `TOO_MANY_ITEMS` |
## Default When Mode Omitted
| Endpoint | Default |
| ---------------------------------------------------- | ------------ |
| **`POST /batch-import/import/entities`** (this page) | **`manual`** |
## Hub vs. API
| Flow | Endpoint | Default mode |
| ----------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Entities** tab (`/bulk-imports?tab=entities`) | **This endpoint** (`POST /batch-import/import/entities`) | User picks in UI (UI default: automatic → send `entityImportMode=automatic`) |
| **Multipart API** (this page) | `POST /batch-import/import/entities` | **Manual** if `entityImportMode` omitted |
| **Custom** (`?tab=custom`) | `POST /batch-import/import/entities` + **`mappingId`** | UI selector (default: automatic) |
See also: [Bulk imports overview](/en/api-reference/bulk-imports/overview).