Skip to main content
POST
Create an entity automatically with enrichment

Overview

The automatic entity creation endpoint allows you to create entities by providing minimal information (tax ID and country). The system automatically:
  • Fetches company/person data from official registries
  • Enriches the entity with additional information
  • Creates related entities (shareholders, directors) based on the specified depth
  • Executes enrichments automatically
This is ideal for KYB (Know Your Business) and KYC (Know Your Customer) processes where you want to onboard entities with complete information automatically.

Endpoint

Authentication

Requires a valid API key in the Authorization header:

Request Body

string
required
Tax identification number of the entity (CNPJ/CPF for Brazil, CUIT/CUIL for Argentina, RUT for Chile).Within an organization, an active taxId (normalized: letters and digits only) may belong to only one entity — whether person or company. If the same type already exists, the API reuses it (alreadyExisted). If another type already holds that tax ID, the request fails with 409 and code DUPLICATE_TAX_ID.Type: string (min length: 1)
string
required
ISO 3166-1 alpha-2 country code. Automatic creation supports BR, AR, and CL only. Any other country returns an error stating automatic creation is not supported for it — use Create an entity instead.Type: string (length: 2)
string
required
Type of entity to create:
  • company - Business entity
  • person - Individual person
Type: enum - 'company' | 'person'
string | null
Optional. ISO 3166-1 alpha-2 or a label the API maps to ISO2; stored on the main entity row (same validation as Create entity).
object
Optional. Same semantics as Create entity, with two maps:
  • main: watchlist for the root entity (taxId in the body) when enrichments run from autoExecuteIntegrations.
  • relationships: watchlist for shareholders / related entities at depth > 0 when enrichments run from autoExecuteIntegrationsShareholders (per company / person).
Today only global_gueno_sanctions_enrichment. Recommended value: { "watchlist": true } or { "watchlist": true, "riskMatrixId": "<uuid>" | null } (legacy boolean also accepted).Each map only affects entities that actually receive that enrichment. Requires the code in the matching enrichment array and org monitoring ON in Marketplace.
string
Your unique identifier for this entity in your system. Optional.When omitted, externalId is set to the normalized tax ID derived from required taxId: letters and digits only, uppercase (no dots, dashes, or spaces). Example: 30-12345678-9 → 30123456789.The taxId column is still saved in the country display format. Same auto-assignment rules as Create an entity (person or company) when taxId is present.Type: string (optional)
number
default:"0"
How many levels of shareholders/relationships to automatically create:
  • 0 - Only create the main entity (no relationships)
  • 1 - Create direct shareholders/directors
  • 2 - Create shareholders and their shareholders
  • Maximum: 5
Type: number (min: 0, max: 5, default: 0)
Brazil + depth > 0 fails the entire request if the discovery enrichments are missing. The API checks this before creating the main entity: it does not create the person or company and then skip related records.
  • Person: both br_bdc_related_companies_enrichment and br_bdc_related_persons_enrichment must be in the resolved main-entity set (autoExecuteIntegrations.enrichments, or all enabled marketplace enrichments when executeAllActiveEnrichments: true). Both must be enabled for the organization. executeAllActiveEnrichments: true does not bypass this if either is disabled or listed in excludeEnrichments.
  • Company: br_bdc_shareholders_enrichment must be in that same resolved set and enabled.
If you cannot run those enrichments, send depth: 0. autoExecuteIntegrationsShareholders only controls enrichments on children after they exist; it does not satisfy this check.
array
Declarative links to existing entities (relatedEntityId / relatedTaxId / relatedExternalId + relationshipType + role). Independent of enrichment depth. Max 10. Missing counterpart → RELATED_ENTITY_NOT_FOUND and the entity is not created. Same semantics as Create entity.
boolean
default:"false"
When true, after linking the counterparts in relationships, also run autoExecuteIntegrationsShareholders enrichments on those existing entities (by related entity type: company vs person lists). Independent of depth.Type: boolean (optional, default: false)
boolean
default:"false"
Mark this entity as a client/customer for tracking purposesType: boolean (default: false)
string | number
Optional registration date for the main entity. ISO 8601 datetime string or epoch milliseconds.Type: string (ISO datetime) | number (optional)
boolean
default:"false"
When true, the creation is enqueued and the API responds immediately with 202 and data.status: "processing" plus a jobId; completion is reported over Socket.IO (see WebSocket Events). When false (default), the request runs synchronously and returns the full result.Type: boolean (optional, default: false)
string
UUID of an automation with trigger create_entity_flow (or entity_created + automatic flow). When sent, the request becomes a creation-flow run: autoExecuteIntegrations, autoExecuteIntegrationsShareholders, and depth are ignored, only that automation runs (enrichments, risk matrix, conditions, and actions live in the workflow), and entity_created is not emitted. If the id is not a valid enabled create_entity_flow automation, the body flow is used instead.Type: string (uuid, optional)
string | string[]
One or more risk matrix UUIDs (legacy: a single UUID string). After creation, active rules tied to those matrices run (unless skipRulesExecution is true).Type: string | string[] | null (optional)
string[]
Preferred for multiple matrices: ordered UUID list. Takes precedence over riskMatrixId when non-empty.Type: string[] (optional)
boolean
default:"false"
Skip automatic rules execution after entity creationType: boolean (optional, default: false)
string
default:"under_review"
Initial status for the entity. Options:
  • active
  • inactive
  • not_started
  • blocked
  • under_review (default)
  • pending_verification - Awaiting KYC/KYB completion
  • awaiting_information - Waiting on client data (e.g. onboarding documents requested by email)
  • suspended
  • expired
  • deleted
  • rejected
Type: enum - 'active' | 'inactive' | 'blocked' | 'under_review' | 'pending_verification' | 'awaiting_information' | 'suspended' | 'expired' | 'deleted' | 'rejected' | 'not_started' (default: ‘under_review’)
object | null
Optional main entity operational hours (timezone + weekly). Persisted on automatic creation the same as manual entity creation. Not applied to shareholders or relationships created via depth.
object
Configure automatic execution of integrations for the main entity. See Provider Codes Reference for available codes.Type: object (optional)Properties:
  • executeAllActiveEnrichments (boolean, optional, default: false) - Execute all active enrichment integrations
  • enrichments (array, optional, default: []) - Array of specific enrichment provider codes to execute
  • enrichmentGroupRefs (array of strings, optional) - Marketplace enrichment group slugs (enrichments only). With executeAllActiveEnrichments: false, groups are resolved and merged with explicit enrichments. With executeAllActiveEnrichments: true, group refs are ignored (not resolved); explicit enrichments may still append after the active set.
  • excludeEnrichments (array, optional, default: []) - Provider codes to omit from the final resolved set (e.g. run all active except listed codes). If the code is the basic-data source that would run (enabled primary or substitute), that creation skips it and uses the next chain member that is enabled and not excluded.
Example:
Do not enable a catalog fallback in Marketplace (and do not list it here) if you only want it when the primary fails. See Marketplace fallbacks.
object
Configure automatic execution of integrations for shareholders and related entities created during the hierarchy traversal. This allows you to specify different integrations for companies vs persons. See Provider Codes Reference for available codes.Type: object (optional)Properties:
  • executeAllActiveEnrichments (boolean, optional, default: false) - Execute all active enrichment integrations for all shareholders
  • enrichments (object, optional) - Specific enrichment provider codes by entity type:
    • company (array, optional, default: []) - Enrichments for company shareholders
    • person (array, optional, default: []) - Enrichments for person shareholders
  • enrichmentGroupRefs (array of strings, optional) - Same group slugs as on the main object; applied to both company and person child pipelines when executeAllActiveEnrichments is false. When executeAllActiveEnrichments is true on this object, group refs are ignored; explicit per-type enrichments may still append after each side’s active set.
  • excludeEnrichments (array, optional, default: []) - Codes omitted from both company and person lists after merge. This also skips basic data for those related entities when the excluded code is the one that would run.
Example:

Required Enrichment Codes by Country

Automatic creation needs at least one basic-data enrichment enabled in Marketplace for that country and entity type (company or person). The canonical primary runs first when it is active and not listed in excludeEnrichments. If it is off or excluded, the first substitute in its chain that is enabled and not excluded runs instead. If none of the chain is available, the request fails before the entity is created.executeAllActiveEnrichments: true only includes enrichments that are enabled. A disabled substitute does not count as a basic-data source. When the primary is active and fails, a substitute may still run with its card off if the catalog has fallback_requires_activation: false. That does not replace the requirement to have one of them enabled in order to start.
When the whole chain is missing, the response is HTTP 422 with success: false and error.code BASIC_DATA_ENRICHMENT_REQUIRED. The text in error.message and data.errors.creationFailed[].error is the same string as the API log (English, truncated at 500 characters). It is not the generic lookup message (We could not complete the basic data lookup for this document.). The text names the codes to activate, in catalog-chain order.
A person in Brazil uses the same sentence with BR person and the person codes in the table below. Argentina and Chile use the same sentence with their own chain. Bulk import in automatic mode stores that same text on the failed row.

Brazil (BR)

Main Entity

These codes must be on the main entity resolved set, not only on autoExecuteIntegrationsShareholders. Missing either related-person enrichment (or shareholders for companies) is a hard fail, not a partial create.
The API runs those enrichments on the main entity to discover shareholders or related people/companies. autoExecuteIntegrationsShareholders only controls what runs on each child after it is created.

Argentina (AR)

Main Entity

Argentina does not support automatic shareholder/relationship creation yet. The depth parameter must be 0. If depth > 0 is provided, the request will fail with an error.

Chile (CL)

Main Entity

Chile does not support automatic shareholder/relationship creation yet. The depth parameter must be 0. If depth > 0 is provided, the request fails.
object
Optional — Client-provided values for the main entity that must not be replaced by registry enrichments. Does not apply to shareholders or related entities (depth > 0).After enrichments run, the API re-applies customData so values are preserved (e.g. automatic name sync from normalized data).Persistence:Documented properties: name, email, phone, birthDate (person), address (string or object with fullAddress, street, city, …), gender (optional enum — other for non-binary).Additional keys (API only): any other key in customData is accepted and stored under entityData.person or entityData.company with the same overwrite protection. E.g. firstName, occupation, tradeName. The dashboard form only sends the documented fields; API integrations may extend the object.Example (person):
Example (company):
object
Optional - Custom attributes as key-value pairs for the created entity.Applied only to the main entity (person or company created), not to shareholders/relationships. Useful for business segments, tags, internal IDs, or any metadata you want to associate at creation time.Structure: object with string keys and values of any type (string, number, boolean, array, etc.).Example:

Query Parameters

boolean
default:"false"
Force re-enrichment of the main entity even if it already exists in the system.Type: boolean (query string: "true" or "false")Behavior:
  • When true: Forces fresh data fetch from official registries and enrichment providers
  • When false or omitted: Uses cached enrichment data if available
  • Overrides organization setting enrichmentsConfig.reEnrichExistingEntities
Use Cases:
  • Periodic compliance reviews requiring updated information
  • Re-validating entity data after regulatory changes
  • Updating company structure after known corporate changes
  • Manual refresh triggered by compliance officers
Example:
Cost Note: May incur additional charges from third-party data providers.
boolean
default:"false"
Force re-enrichment of ALL shareholders and related entities in the corporate structure.Type: boolean (query string: "true" or "false")Behavior:
  • When true: Forces fresh data fetch for the main entity AND all shareholders at all levels (up to depth)
  • When false or omitted: Only refreshes the main entity if refresh=true, shareholders use cached data
  • Works in combination with the depth parameter to determine how deep to refresh
  • Overrides organization setting for all related entities
Use Cases:
  • Complete corporate structure audit
  • Due diligence requiring up-to-date ownership chain
  • Annual compliance reviews of entire corporate tree
  • Investigation of complex ownership structures
Example - Refresh entire structure:
This will refresh the main company AND all shareholders up to 3 levels deep.Performance Note:
  • Setting this to true with high depth values (4-5) can take several minutes
  • May result in significant costs if the corporate structure is complex
  • Consider using selectively for high-risk entities only
Best Practice:
  • Use refresh=true alone for single entity updates
  • Use reEnrichExistingChildEntities=true only when you need full ownership chain validation

Response

By default the endpoint executes synchronously and returns the complete result including the main entity and all related entities created. With runInBackground: true the response is 202 and the work continues in the background:
boolean
Indicates if the entity was created successfully
object
Complete information about the creation:
  • entity (object) - The main entity created with all its data
  • shareholders (array) - Child entities materialized in that run (companies only). Each item is { id, name, taxId, type }. Percentage and roles are stored on the relationship; read them later with Get materialized shareholders.
  • relationships (array) - Array of related entities created (for persons)
  • summary (object):
    • entitiesCreated (number) - Total number of entities created
    • relationshipsCreated (number) - Total number of relationships created
    • errorsCount (number) - Number of errors encountered
  • errors (object, optional) - Details of any errors that occurred:
    • creationFailed (array) - Failed entity creations
    • enrichmentFailed (array) - Extra enrichments that failed after the entity was persisted (entityId + failedProviders). Empty when basic-data fails and the entity is not created. Each failedProviders item has providerCode, error (English), and optional code. When the request asked for an enrichment the organization has not enabled, code is INTEGRATION_NOT_ENABLED (also INTEGRATION_NOT_CONFIGURED, INTEGRATION_BLOCKED, INTEGRATION_GLOBALLY_DISABLED, CONTRACT_ACCESS_NOT_INCLUDED, INTEGRATION_NOT_FOUND). Those codes are not retried. Other enrichments in the same request still run, and success stays true when the entity was created.
    • enrichmentFailedDetails (array, additive) - Each basic-data attempt that failed (primary + catalog fallbacks) when the entity was not created. Items: providerCode (marketplace code), code (semantic, e.g. DOCUMENT_RESTRICTED, UPSTREAM_CREDITS_ERROR), errorMessage (English). Also nested on the matching creationFailed[] row.
For organizations where this setting is enabled, if the primary source identifies a person as a minor, the entity is immediately created as Person <taxId> with attributes.isMinor: true. Retries, fallbacks, and additional enrichments are skipped; risk analysis runs normally. This behavior is disabled by default.
object
Result of rules execution (only present when rules ran, e.g. when skipRulesExecution is false and a risk matrix is configured via riskMatrixId or riskMatrixIds), or null. When present, includes:
  • success (boolean) - Whether rules executed successfully
  • rulesTriggered (number) - Number of rules that were triggered
  • alerts (array) - Alerts generated by rules
  • riskScore (number) - Final calculated risk score
  • decision (string) - Final decision (APPROVE, REJECT, HOLD, REVIEW_REQUIRED)
  • rulesExecutionSummary (object) - Present when rules ran. See below for structure.
object
At the root of the response (same as transactions API). Same value as rulesResult.rulesExecutionSummary. Only present when rules ran (e.g. skipRulesExecution is false and risk matrix was executed). Summary of which rules matched (hit) vs did not match (no hit), executed actions, and total score. Omitted when rules did not run. See Rules Execution Summary for the full structure and a complete example.
  • rulesHit (array) - Rules whose conditions were met. Each item: name, description, score, priority, category, status (e.g. active, shadow), conditions (array of { field, value, operator? }), actions (alerts, suggestion, status, assignedUser).
  • rulesNoHit (array) - Rules that were evaluated but conditions were not met. Same structure as rulesHit (includes configured actions, not executed).
  • actionsExecuted (object) - Aggregated executed actions across all rules that hit: alerts (array of { name?, type?, severity?, description? }), suggestion (BLOCK | SUSPEND | FLAG, highest weight), status (entity status applied, if any), assignedUser ({ userId }, if any), customKeys (array of strings, optional) — custom action keys from matched rules; for integrations/workflows.
  • totalScore (number) - Sum of score of all rules that hit and are not in shadow status.

WebSocket Events

The system emits real-time events during the creation process:

entity:creation-started

Emitted when the creation process begins.

entity:creation-completed

Emitted when the entity and all relationships have been created.

entity:creation-failed

Emitted if the creation process fails.

Gu1 Sanctions Monitoring on Automatic Create

For POST /entities/automatic: Today the only body-monitoring code is global_gueno_sanctions_enrichment. It must appear in the enrichment array for that level and in main or relationships with watchlist enabled.
Registry enrichments (e.g. ar_afip_registration_enrichment) ignore monitoring and always run as one-off queries.
This payload only illustrates monitoring and Gu1 enrichment codes. A real request must still include the mandatory registry enrichments for the chosen country and type (see Required Enrichment Codes by Country above), or automatic creation will fail.

Examples

Create Company with Shareholders (Depth 1)

Create Person (KYC) with Specific Integrations

Create Argentine Company (No Shareholders Support)

Create Brazilian Company with Shareholders and Selective Integrations

Response Example

Successful Company Creation with Shareholders

For Brazilian companies, entityData.company.cnae and cnaeDescription contain the main economic activity from the normalized basic-data result. industry contains the same activity description for compatibility with existing entity profiles.

Successful Person Creation

Error Responses

400 Bad Request - Invalid Tax ID

404 Not Found - Entity Not Found in Registry

409 Conflict - Entity Already Exists

Returned when the normalized taxId is already used by an active entity of a different type in the same organization (person vs company). Same-type matches are reused instead of failing.

500 Internal Server Error

Best Practices

  1. Use depth wisely: Higher depth values (3-5) can create many entities and take longer to complete. Start with depth 0-1 for testing.
  2. Monitor WebSocket events: While the API returns synchronously, WebSocket events are also emitted for real-time UI updates (entity:creation-started, entity:creation-completed, entity:creation-failed).
  3. Handle timeouts: For complex hierarchies with high depth, the request can take several minutes. Configure appropriate HTTP timeout values in your client.
  4. Error handling: Always check the success field and the errors object in the response. Some entities may be created successfully while others fail.
  5. Rate limiting: Be mindful of rate limits when creating multiple entities in quick succession. The endpoint fetches data from external APIs which may have their own rate limits.