Import entities (CSV)

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

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

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:

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)

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

  -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) 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 — use with entityImportMode=automatic. AR/BR/CL demo rows, depth, create_relationships, execute_all_active_enrichments.
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):

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):

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.
`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. 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.
`status`	—	`status`	One of: `active`, `inactive`, `blocked`, `under_review`, `suspended`, `pending_verification`, `expired`, `deleted`, `rejected`.
`attributes.<path>`	—	`attributes`	Nested business data (same dot notation as native transaction CSV). E.g. `attributes.segment_tag`, `attributes.tags.tier`.
`entityData.<path>`	—	`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.<path>`	—	`entityData.person`	Explicit person path.
`entityData.company.<path>`	—	`entityData.company`	Explicit company path.
`metadata.<path>`	—	`attributes` (legacy)	Deprecated; merged into `attributes`. Prefer `attributes.*`.
Unprefixed column	—	`attributes`	Backward compatible: `segment_tag` → `attributes.segment_tag`.

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.

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.

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:

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

{
  "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):

-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): 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)

​Endpoint

​Overview

​Authentication

​Import Modes (entityImportMode)

​Default When Sending Only the CSV

​Manual with Selected Enrichments

​Automatic Mode (Explicit)

​Manual without Post-Create Rules

​Platform CSV (no mappingId)

​Country (ISO2) — Always Required

​Column Reference (Platform CSV)

​Related-Entity Enrichments per Row (Platform CSV)

​Custom CSV

​Form Fields

​Success Response

​Child Enrichments & Monitoring

​Manual vs. Automatic (Same Job Queue)

​Limits

​Default When Mode Omitted

​Hub vs. API

Endpoint

Overview

Authentication

Import Modes (`entityImportMode`)

Default When Sending Only the CSV

Manual with Selected Enrichments

Automatic Mode (Explicit)

Manual without Post-Create Rules

Platform CSV (no `mappingId`)

Country (ISO2) — Always Required

Column Reference (Platform CSV)

Related-Entity Enrichments per Row (Platform CSV)

Custom CSV

Form Fields

Success Response

Child Enrichments & Monitoring

Manual vs. Automatic (Same Job Queue)

Limits

Default When Mode Omitted

Hub vs. API