Create Automatically

Automatically create with enriched data from registries

POST /entities/automatic

Create Automatically

cURL

curl --request POST \
  --url http://api.gu1.ai/entities/automatic \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taxId": "<string>",
  "country": "<string>",
  "type": "<string>",
  "externalId": "<string>",
  "depth": 123,
  "isClient": true,
  "riskMatrixId": "<string>",
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "customData": {},
  "attributes": {}
}
'

200

{
  "success": true,
  "data": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

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

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

POST http://api.gu1.ai/entities/automatic

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Body

taxId · string · required

Tax identification number of the entity (e.g., CNPJ for Brazil, RFC for Mexico, CUIT for Argentina)

Type: string (min length: 1)

country · string · required

ISO 3166-1 alpha-2 country code (e.g., “BR”, “MX”, “AR”, “CL”)

Type: string (length: 2)

type · string · required

Type of entity to create:

• company - Business entity
• person - Individual person

Type: enum - 'company' | 'person'

externalId · string

Your unique identifier for this entity in your system (optional, will be auto-generated if not provided)

Type: string (optional)

depth · 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)

isClient · boolean · default: "false"

Mark this entity as a client/customer for tracking purposes

Type: boolean (default: false)

riskMatrixId · string

UUID of the risk matrix to execute rules from automatically

Type: string | null (optional)

skipRulesExecution · boolean · default: "false"

Skip automatic rules execution after entity creation

Type: boolean (optional, default: false)

status · string · default: "under_review"

Initial status for the entity. Options:

• active
• inactive
• blocked
• under_review (default)
• suspended
• expired
• deleted
• rejected

Type: enum - 'active' | 'inactive' | 'blocked' | 'under_review' | 'suspended' | 'expired' | 'deleted' | 'rejected' (default: ‘under_review’)

autoExecuteIntegrations · 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
• executeAllActiveChecks (boolean, optional, default: false) - Execute all active check integrations
• enrichments (array, optional, default: []) - Array of specific enrichment provider codes to execute
• checks (array, optional, default: []) - Array of specific check provider codes to execute

{
  executeAllActiveEnrichments?: boolean; // default: false
  executeAllActiveChecks?: boolean; // default: false
  enrichments?: ValidProviderCodesEnum[]; // default: []
  checks?: ValidProviderCodesEnum[]; // default: []
}

Example:

{
  "executeAllActiveEnrichments": false,
  "enrichments": ["br_cpfcnpj_complete_company_enrichment", "br_bdc_shareholders_enrichment"],
  "checks": ["pep_check", "sanctions_check"]
}

autoExecuteIntegrationsShareholders · 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
• executeAllActiveChecks (boolean, optional, default: false) - Execute all active check 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
• checks (object, optional) - Specific check provider codes by entity type:
  • company (array, optional, default: []) - Checks for company shareholders
  • person (array, optional, default: []) - Checks for person shareholders

{
  executeAllActiveEnrichments?: boolean; // default: false
  executeAllActiveChecks?: boolean; // default: false
  enrichments?: {
    company?: ValidProviderCodesEnum[]; // default: []
    person?: ValidProviderCodesEnum[]; // default: []
  };
  checks?: {
    company?: ValidProviderCodesEnum[]; // default: []
    person?: ValidProviderCodesEnum[]; // default: []
  };
}

Example:

{
  "executeAllActiveEnrichments": false,
  "executeAllActiveChecks": false,
  "enrichments": {
    "company": ["br_cpfcnpj_complete_company_enrichment"],
    "person": ["br_bdc_basic_data_enrichment"]
  },
  "checks": {
    "company": ["sanctions_check"],
    "person": ["pep_check", "sanctions_check"]
  }
}

Required Enrichment Codes by Country

When using specific enrichment codes (not executeAllActiveEnrichments: true), certain enrichments are mandatory for the automatic creation to work. Without them, the system cannot fetch basic entity data from official registries and the request will fail.

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

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.

customData · object

Optional - Field overrides for the main entity only (not shareholders or related entities created when depth > 0).

When customData.name is set to a non-empty string, that value is stored as the entity name and is not overwritten by the name from basic-data enrichment or by automatic name sync after additional enrichments. If you omit customData or omit name, behavior is unchanged: the name comes from the provider/registry as today.

Type: object (optional)

Properties:

• name (string, optional) - Display name for the main entity. If present, must be a non-empty string (API validation).

Example:

{
  "name": "Acme Corp (display name)"
}

attributes · 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:

{
  "businessSegments": ["retail", "fintech"],
  "source": "onboarding_web",
  "tags": ["vip", "high_volume"]
}

Query Parameters

refresh · 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:

POST http://api.gu1.ai/entities/automatic?refresh=true

Cost Note: May incur additional charges from third-party data providers.

refreshShareholders · 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:

POST http://api.gu1.ai/entities/automatic?refreshShareholders=true&depth=3

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 refreshShareholders=true only 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.

success · boolean

Indicates if the entity was created successfully

data · object

Complete information about the creation:

• entity (object) - The main entity created with all its data
• shareholders (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 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) - Failed enrichment executions

rulesResult · object

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.

rulesExecutionSummary · 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.

{
  "taxId": "12.345.678/0001-90",
  "type": "company",
  "userId": "user_id"
}

entity:creation-completed

Emitted when the entity and all relationships have been created.

{
  "success": true,
  "mainEntity": {
    "id": "uuid",
    "name": "Company Name",
    "taxId": "12.345.678/0001-90"
  },
  "stats": {
    "totalEntitiesCreated": 15,
    "companiesCreated": 8,
    "peopleCreated": 7,
    "relationshipsCreated": 14
  }
}

entity:creation-failed

Emitted if the creation process fails.

{
  "success": false,
  "error": "Error message",
  "taxId": "12.345.678/0001-90"
}

Examples

Create Company with Shareholders (Depth 1)

cURL

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "12.345.678/0001-90",
    "country": "BR",
    "type": "company",
    "depth": 1,
    "isClient": true,
    "autoExecuteIntegrations": {
      "executeAllActiveEnrichments": true,
      "executeAllActiveChecks": true
    }
  }'

Create Person (KYC) with Specific Integrations

cURL

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "123.456.789-00",
    "country": "BR",
    "type": "person",
    "externalId": "customer_12345",
    "depth": 0,
    "autoExecuteIntegrations": {
      "enrichments": ["br_bdc_basic_data_enrichment"]
    }
  }'

Create Argentine Company (No Shareholders Support)

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "30-12345678-9",
    "country": "AR",
    "type": "company",
    "depth": 0,
    "isClient": true,
    "riskMatrixId": "risk_matrix_uuid",
    "autoExecuteIntegrations": {
      "enrichments": ["ar_nosis_extended_verification_enrichment"]
    }
  }'

Create Brazilian Company with Shareholders and Selective Integrations

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "12.345.678/0001-90",
    "country": "BR",
    "type": "company",
    "depth": 2,
    "isClient": true,
    "riskMatrixId": "risk_matrix_uuid",
    "autoExecuteIntegrations": {
      "enrichments": ["br_cpfcnpj_complete_company_enrichment", "br_bdc_shareholders_enrichment"]
    },
    "autoExecuteIntegrationsShareholders": {
      "enrichments": {
        "company": ["br_cpfcnpj_complete_company_enrichment"],
        "person": ["br_bdc_basic_data_enrichment"]
      }
    }
  }'

Response Example

Successful Company Creation with Shareholders

{
  "success": true,
  "data": {
    "entity": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organizationId": "org_uuid",
      "type": "company",
      "name": "Tech Solutions LTDA",
      "taxId": "12345678000190",
      "countryCode": "BR",
      "status": "under_review",
      "riskScore": null,
      "entityData": {
        "company": {
          "legalName": "Tech Solutions LTDA",
          "tradeName": "Tech Solutions",
          "incorporationDate": "2020-01-15",
          "industry": "Technology"
        }
      },
      "createdAt": "2024-12-23T10:30:00.000Z",
      "updatedAt": "2024-12-23T10:30:00.000Z"
    },
    "shareholders": [
      {
        "id": "shareholder_1_uuid",
        "type": "person",
        "name": "João Silva",
        "taxId": "12345678900",
        "countryCode": "BR",
        "entityData": {
          "person": {
            "firstName": "João",
            "lastName": "Silva"
          }
        },
        "shareholderInfo": {
          "percentage": 60.0,
          "role": "Sócio Administrador"
        }
      },
      {
        "id": "shareholder_2_uuid",
        "type": "person",
        "name": "Maria Santos",
        "taxId": "98765432100",
        "countryCode": "BR",
        "entityData": {
          "person": {
            "firstName": "Maria",
            "lastName": "Santos"
          }
        },
        "shareholderInfo": {
          "percentage": 40.0,
          "role": "Sócia"
        }
      }
    ],
    "summary": {
      "entitiesCreated": 3,
      "relationshipsCreated": 2,
      "errorsCount": 0
    }
  },
  "rulesResult": null
}

Successful Person Creation

{
  "success": true,
  "data": {
    "entity": {
      "id": "person_uuid",
      "organizationId": "org_uuid",
      "type": "person",
      "name": "João Silva",
      "taxId": "12345678900",
      "countryCode": "BR",
      "status": "under_review",
      "entityData": {
        "person": {
          "firstName": "João",
          "lastName": "Silva",
          "dateOfBirth": "1985-05-15"
        }
      },
      "createdAt": "2024-12-23T10:30:00.000Z",
      "updatedAt": "2024-12-23T10:30:00.000Z"
    },
    "relationships": [],
    "summary": {
      "entitiesCreated": 1,
      "relationshipsCreated": 0,
      "errorsCount": 0
    }
  },
  "rulesResult": null
}

Error Responses

400 Bad Request - Invalid Tax ID

{
  "success": false,
  "error": "Invalid CNPJ format for Brazil"
}

404 Not Found - Entity Not Found in Registry

{
  "success": false,
  "error": "Entity not found in official registry",
  "details": {
    "taxId": "12.345.678/0001-90",
    "country": "BR",
    "registry": "Receita Federal"
  }
}

409 Conflict - Entity Already Exists

{
  "success": false,
  "error": "Entity with this tax ID already exists",
  "details": {
    "existingEntityId": "uuid",
    "taxId": "12.345.678/0001-90"
  }
}

500 Internal Server Error

{
  "success": false,
  "error": "Failed to create entity automatically",
  "details": {
    "message": "External API timeout"
  }
}

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.

Related Endpoints

• Create Entity Manually - Create entities with your own data
• Get Entity - Retrieve entity details
• List Entities - Query your entities