Create an entity automatically with enrichment
Create an entity automatically with enrichment
Automatically create with enriched data from registries — in the gu1 universal entity model for KYC, KYB, and risk analysis, with examples for create automatic.
POST
Create an entity automatically with enrichment
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.
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 integrations (checks and enrichments) automatically
Endpoint
Authentication
Requires a valid API key in the Authorization header:Request Body
Tax identification number of the entity (e.g., CNPJ for Brazil, RFC for Mexico, CUIT for Argentina)Type:
string (min length: 1)ISO 3166-1 alpha-2 country code (e.g., “BR”, “MX”, “AR”, “CL”)Type:
string (length: 2)Type of entity to create:
company- Business entityperson- Individual person
enum - 'company' | 'person'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).
Optional. Same semantics as Create entity, with two maps:
main: watchlist for the root entity (taxIdin the body) when enrichments run fromautoExecuteIntegrations.relationships: watchlist for shareholders / related entities atdepth> 0 when enrichments run fromautoExecuteIntegrationsShareholders(percompany/person).
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.Your unique identifier for this entity in your system (optional, will be auto-generated if not provided)Type:
string (optional)How many levels of shareholders/relationships to automatically create:
0- Only create the main entity (no relationships)1- Create direct shareholders/directors2- Create shareholders and their shareholders- Maximum:
5
number (min: 0, max: 5, default: 0)Mark this entity as a client/customer for tracking purposesType:
boolean (default: false)UUID of the risk matrix to execute rules from automaticallyType:
string | null (optional)Skip automatic rules execution after entity creationType:
boolean (optional, default: false)Initial status for the entity. Options:
activeinactiveblockedunder_review(default)suspendedexpireddeletedrejected
enum - 'active' | 'inactive' | 'blocked' | 'under_review' | 'suspended' | 'expired' | 'deleted' | 'rejected' (default: ‘under_review’)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.Configure automatic execution of integrations for the main entity. See Provider Codes Reference for available codes.Type: Example:
object (optional)Properties:executeAllActiveEnrichments(boolean, optional, default:false) - Execute all active enrichment integrationsenrichments(array, optional, default:[]) - Array of specific enrichment provider codes to executeenrichmentGroupRefs(array of strings, optional) - Marketplace enrichment group slugs (enrichments only). WithexecuteAllActiveEnrichments: false, groups are resolved and merged with explicitenrichments. WithexecuteAllActiveEnrichments: true, group refs are ignored (not resolved); explicitenrichmentsmay 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)
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: Example:
object (optional)Properties:executeAllActiveEnrichments(boolean, optional, default:false) - Execute all active enrichment integrations for all shareholdersenrichments(object, optional) - Specific enrichment provider codes by entity type:company(array, optional, default:[]) - Enrichments for company shareholdersperson(array, optional, default:[]) - Enrichments for person shareholders
enrichmentGroupRefs(array of strings, optional) - Same group slugs as on the main object; applied to bothcompanyandpersonchild pipelines whenexecuteAllActiveEnrichmentsisfalse. WhenexecuteAllActiveEnrichmentsistrueon this object, group refs are ignored; explicit per-typeenrichmentsmay still append after each side’s active set.excludeEnrichments(array, optional, default:[]) - Codes omitted from bothcompanyandpersonlists after merge
Required Enrichment Codes by Country
Brazil (BR)
Main Entity
| Entity Type | Required Enrichment Code | Description |
|---|---|---|
| Company | br_cpfcnpj_complete_company_enrichment | Fetches company data from CNPJ/Receita Federal (legal name, trade name, address, industry, etc.) |
| Person | br_bdc_basic_data_enrichment | Fetches person data via BDC/CPF (full name, date of birth, address, etc.) |
Shareholders / Related Entities (only when depth > 0)
| Main Entity Type | Required Enrichment Code(s) | Description |
|---|---|---|
| Company | br_bdc_shareholders_enrichment | Fetches the QSA (Quadro Societário) to discover company shareholders and directors |
| Person | br_bdc_related_companies_enrichment AND br_bdc_related_persons_enrichment | Both are required. Fetches companies and persons related to the individual |
The shareholder enrichments must be included in the main entity’s
autoExecuteIntegrations.enrichments array (not in autoExecuteIntegrationsShareholders), because the system needs to run them on the main entity to discover who the shareholders are. The autoExecuteIntegrationsShareholders field controls what enrichments to run on each shareholder after they are created.Argentina (AR)
Main Entity
| Entity Type | Required Enrichment Code | Description |
|---|---|---|
| Company | ar_nosis_extended_verification_enrichment | Fetches company data from Nosis (legal name, CUIT status, address, activities, etc.) |
| Person | ar_nosis_extended_verification_enrichment | Same provider for both entity types |
Shareholders / Related Entities
Optional — Client-provided values for the main entity that must not be replaced by registry enrichments. Does not apply to shareholders or related entities (
Documented properties: Example (company):
depth > 0).After enrichments run, the API re-applies customData so values are preserved (e.g. automatic name sync from normalized data).Persistence:customData field | Root (entities) | entityData |
|---|---|---|
name | name | — |
email | email | person.email / company.email |
phone | phone | person.phone / company.phone |
birthDate | — | person.dateOfBirth only (person) |
address | — | person.address or company.address |
gender | — | person.gender (AR, CUIL derivation) |
name, email, phone, birthDate (person), address (string or object with fullAddress, street, city, …), gender (optional, AR).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):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
Force re-enrichment of the main entity even if it already exists in the system.Type: Cost Note: May incur additional charges from third-party data providers.
boolean (query string: "true" or "false")Behavior:- When
true: Forces fresh data fetch from official registries and enrichment providers - When
falseor omitted: Uses cached enrichment data if available - Overrides organization setting
enrichmentsConfig.reEnrichExistingEntities
- 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
Force re-enrichment of ALL shareholders and related entities in the corporate structure.Type: This will refresh the main company AND all shareholders up to 3 levels deep.Performance Note:
boolean (query string: "true" or "false")Behavior:- When
true: Forces fresh data fetch for the main entity AND all shareholders at all levels (up todepth) - When
falseor omitted: Only refreshes the main entity ifrefresh=true, shareholders use cached data - Works in combination with the
depthparameter to determine how deep to refresh - Overrides organization setting for all related entities
- Complete corporate structure audit
- Due diligence requiring up-to-date ownership chain
- Annual compliance reviews of entire corporate tree
- Investigation of complex ownership structures
- Setting this to
truewith highdepthvalues (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
- Use
refresh=truealone for single entity updates - Use
reEnrichExistingChildEntities=trueonly when you need full ownership chain validation
Response
The endpoint executes synchronously and returns the complete result including the main entity and all related entities created.Indicates if the entity was created successfully
Complete information about the creation:
entity(object) - The main entity created with all its datashareholders(array) - Array of shareholder entities created (for companies)relationships(array) - Array of related entities created (for persons)summary(object):entitiesCreated(number) - Total number of entities createdrelationshipsCreated(number) - Total number of relationships createderrorsCount(number) - Number of errors encountered
errors(object, optional) - Details of any errors that occurred:creationFailed(array) - Failed entity creationsenrichmentFailed(array) - Failed enrichment executions
Result of rules execution (only present when rules ran, e.g. when skipRulesExecution is
false and riskMatrixId is provided), 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.
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
shadowstatus.
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
ForPOST /entities/automatic:
| Field | Applies to |
|---|---|
monitoring.main | Root entity when enrichments run from autoExecuteIntegrations. |
monitoring.relationships | Each shareholder/related entity at depth > 0 when enrichments run from autoExecuteIntegrationsShareholders. |
global_gueno_sanctions_enrichment. It must appear in the enrichment array for that level and in main or relationships with watchlist enabled.
ar_afip_registration_enrichment) ignore monitoring and always run as one-off queries.
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
Successful Person Creation
Error Responses
400 Bad Request - Invalid Tax ID
404 Not Found - Entity Not Found in Registry
409 Conflict - Entity Already Exists
500 Internal Server Error
Best Practices
- Use depth wisely: Higher depth values (3-5) can create many entities and take longer to complete. Start with depth 0-1 for testing.
-
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). - Handle timeouts: For complex hierarchies with high depth, the request can take several minutes. Configure appropriate HTTP timeout values in your client.
-
Error handling: Always check the
successfield and theerrorsobject in the response. Some entities may be created successfully while others fail. - 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.
Related Endpoints
- Create Entity Manually - Create entities with your own data
- Get Entity - Retrieve entity details
- List Entities - Query your entities