Skip to main content
POST
Create a person automatically with enrichment

Overview

The automatic person creation endpoint allows you to create persons by providing minimal information (tax ID and country). The system automatically:
  • Fetches person data from official registries
  • Enriches the person with additional information
  • Executes enrichments automatically
This is ideal for KYC (Know Your Customer) processes where you want to onboard customers with complete information automatically.

Endpoint

Authentication

Requires a valid API key in the Authorization header:

Request Body

string
required
Tax identification number of the person (e.g., CPF for Brazil, CURP for Mexico, CUIT for Argentina)
📋 See Tax ID Formats by Country for accepted formats and validation rules for each country.
string
required
ISO 3166-1 alpha-2 country code (e.g., “BR”, “MX”, “AR”, “CL”)
string
required
Must be set to person
string
Your unique identifier for this person (optional, will be auto-generated if not provided)
boolean
default:"false"
Mark this person as a client/customer for tracking purposes
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).
string[]
Preferred for multiple matrices: ordered UUID list. Takes precedence over riskMatrixId when non-empty.
boolean
default:"false"
Skip automatic rules execution after person creation
string
default:"under_review"
Initial status. Default under_review. Optional: not_started, active, inactive, blocked, under_review, pending_verification, awaiting_information, suspended, expired, deleted, rejected. See Entities overview — Entity Status.
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.
number
default:"0"
Depth of relationship extraction (0-5). Controls how many levels of relationships to automatically fetch and create.
  • 0: No relationships (only main entity)
  • 1: Direct relationships only
  • 2: Relationships + their relationships
  • 3-5: Additional levels (use with caution - can create many entities)
Brazil + depth > 0 fails the entire request if both discovery enrichments are missing. The API checks this before creating the person: it does not create the main entity and then skip related records.
  • Required enrichments: br_bdc_related_companies_enrichment and br_bdc_related_persons_enrichment — both.
  • Where: in the resolved main-entity set (autoExecuteIntegrations.enrichments, or all enabled marketplace enrichments when executeAllActiveEnrichments: true), and enabled for the organization.
  • executeAllActiveEnrichments: true does not bypass this if either is disabled or listed in excludeEnrichments.
  • autoExecuteIntegrationsShareholders does not satisfy this check: it only controls enrichments on children after they exist.
If you cannot run those enrichments, send depth: 0 — the API creates only the person.
object
Configure automatic execution of integrations for the main person 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.
Example:
object
Configure automatic execution of integrations for discovered relationships. Useful when using depth > 0. See Provider Codes Reference for available codes.Type: object (optional)Properties:
  • executeAllActiveEnrichments (boolean, optional, default: false) - Execute all active enrichments on related entities
  • enrichments (object, optional) - Specific enrichments by entity type
    • company (array, default: []) - Enrichments for company relationships
    • person (array, default: []) - Enrichments for person relationships
  • enrichmentGroupRefs (array of strings, optional) - Same slugs as on the main object; applied to both company and person 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.
Example:

Required Enrichment Codes by Country

The person is created only if at least one of these codes is enabled in Marketplace. The primary runs when it is active; otherwise the first enabled substitute runs:
  • Brazil: br_bdc_basic_data_enrichment, then br_cpfcnpj_complete_person_enrichment, br_cpfcnpj_complete_person_9_enrichment
  • Argentina: ar_nosis_extended_verification_enrichment, then ar_arca_contribuyente_enrichment when that one is enabled
  • Chile: cl_baseapi_basic_data_person_enrichment only
If none is enabled, the response is HTTP 422 with error.code BASIC_DATA_ENRICHMENT_REQUIRED. error.message and data.errors.creationFailed[].error carry the same English sentence as the API log (Activate one of: …). Full body: Automatic entity creation.

Brazil (BR)

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

Argentina (AR)

Argentina does not support automatic relationship creation yet. The depth parameter must be 0.
object
Optional — Client values for the main person that must not be replaced by enrichments. Full reference (root vs entityData): Automatic entity creation.Fields: name, email, phone, birthDate → entityData.person.dateOfBirth, address → entityData.person.address, gender (enum: M | F | male | female | other | unknown — use other for non-binary; see Create entity).Example:
object
Optional - Custom attributes as key-value pairs for the created entity.Applied only to the main entity (the person created), not to relationships/shareholders. 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:

Response

boolean
Indicates if the person was created successfully
object
Complete information about the creation:
  • entity (object) - The person created with all data
  • summary (object) - Creation summary
  • errors (object, optional) - Details of any errors
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, 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.

Examples

Create Person with All Active Integrations

Create Person with Specific Integrations

Response Example

Error Responses

400 Bad Request - Invalid Tax ID

404 Not Found - Person Not Found in Registry

409 Conflict - Person Already Exists

Best Practices

  1. Error handling: Always check the success field in the response
  2. Rate limiting: Be mindful of rate limits when creating multiple persons
  3. Integration selection: Choose specific integrations for better control over cost and performance

Next Steps