Bulk entity import (JSON)

curl --request POST \
  --url http://api.gu1.ai/entities/automatic/bulk \
  --header 'Authorization: Bearer <token>'

POST

entities

automatic

bulk

Bulk entity import (JSON)

curl --request POST \
  --url http://api.gu1.ai/entities/automatic/bulk \
  --header 'Authorization: Bearer <token>'

Endpoint

POST https://api.gu1.ai/entities/automatic/bulk

Overview

Content-Type: application/json. Used by the Bulk imports → Entities hub (/bulk-imports?tab=entities) and integrations that already parsed rows to JSON. Enqueues the same job as Import entities (CSV). Requires entities:bulk_import, entities:create, and org bulk automatic entity import enabled.

Authentication

Authorization: Bearer YOUR_API_KEY

Import modes (`importMode`)

Mode	Default	Behavior
`automatic_enriched`	Yes (when omitted)	Basic data by tax ID for AR, BR, or CL + enrichments (`autoExecuteIntegrations`) + optional `depth`
`manual_no_enrichment`	No (explicit)	Minimal entity; `suggestedName` required on every item; selected enrichments via `autoExecuteIntegrations` (no basic-data pipeline); `depth` = 0; any valid platform ISO2

vs multipart CSV

	This endpoint (JSON)	POST /batch-import/import/entities
Default	Automatic	Manual
Manual + enrichments	Yes (`autoExecuteIntegrations`)	Yes (`autoExecuteIntegrations` / per-row CSV columns)
Input	JSON `items[]`	CSV multipart

Body (summary)

Field	Required	Description
`items`	Yes	Row array (`taxId`, `type`, …)
`importMode`	No	`automatic_enriched` (default) or `manual_no_enrichment`
`country`	Conditional	Batch ISO2 when rows omit `country`
`riskMatrixPersonId` / `riskMatrixCompanyId`	No	UUID
`autoExecuteIntegrations`	No	`{ executeAllActiveEnrichments, enrichments, enrichmentGroupRefs, excludeEnrichments }`
`autoExecuteIntegrationsShareholders`	No	When `depth` > 0
`depth`	No	0–5 (automatic mode)
`skipRulesExecution`	No	default `false`
`stopOnFirstError`	No	default `false`
`monitoring`	No	`{ main, relationships? }`
`reportRecipientEmails`	No	Up to 10 emails
`emailLocale`	No	`en` / `es` / `pt`

Per item (`items[]`)

Field	Description
`taxId`, `type`	Required
`country`	Optional ISO2 per row
`suggestedName`	Required in manual mode
`gender`, `email`, `phone`, `externalId`, `attributes`, `status`, `riskMatrixId`, …	Optional

Supported countries: automatic → AR, BR, CL; manual → any valid platform ISO2 (batch and/or per row).

Limits

	Value
Max `items` per request	Default 300 (server env `BULK_AUTOMATIC_ENTITY_MAX_ITEMS`; not the plan table used for CSV)
Over limit	`400` `TOO_MANY_ITEMS`

For large CSV imports with plan-based limits (up to 100,000 rows), use Import entities (CSV) instead. See Bulk imports overview for the full limits matrix (transactions, entities CSV, user events).

Example — automatic

{
  "country": "AR",
  "importMode": "automatic_enriched",
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": true,
    "enrichments": []
  },
  "items": [
    { "taxId": "20123456789", "type": "company" }
  ]
}

Example — manual with selected enrichments

{
  "country": "AR",
  "importMode": "manual_no_enrichment",
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": ["some_enrichment_code"]
  },
  "items": [
    {
      "taxId": "20123456789",
      "type": "company",
      "suggestedName": "Demo Company SA"
    }
  ]
}

Response

{
  "success": true,
  "jobId": "bulk-entity-…",
  "totalItems": 1
}

Follow-up

GET /entities/automatic/bulk/imports
GET /entities/automatic/bulk/imports/{jobId}/failures.csv

Documentation Index

​Endpoint

​Overview

​Authentication

​Import modes (importMode)

​vs multipart CSV

​Body (summary)

​Per item (items[])

​Limits

​Example — automatic

​Example — manual with selected enrichments

​Response

​Follow-up