Create Automatically

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 purposesType: boolean (default: false)

riskMatrixId

string

UUID of the risk matrix to execute rules from automaticallyType: string | null (optional)

skipRulesExecution

boolean

default:"false"

Skip automatic rules execution after entity creationType: boolean (optional, default: false)

status

string

default:"under_review"

Initial status for the entity. Options:

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

Type: enum -

'active' | 'inactive' | 'blocked' | 'under_review' | 'suspended' | 'pending_verification' | '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": true,
  "executeAllActiveChecks": false,
  "enrichments": ["serpro_cnpj", "receita_federal"],
  "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": ["serpro_cnpj", "receita_federal"],
    "person": ["serpro_cpf"]
  },
  "checks": {
    "company": ["sanctions_check"],
    "person": ["pep_check", "sanctions_check"]
  }
}

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 -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 -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": ["serpro_cpf", "bureau_credit"],
      "checks": ["pep_check", "sanctions_check"]
    }
  }'

Create Company with Deep Hierarchy 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": "30-12345678-9",
    "country": "AR",
    "type": "company",
    "depth": 2,
    "isClient": true,
    "riskMatrixId": "risk_matrix_uuid",
    "autoExecuteIntegrations": {
      "executeAllActiveEnrichments": true
    },
    "autoExecuteIntegrationsShareholders": {
      "enrichments": {
        "company": ["afip_company"],
        "person": ["renaper_dni"]
      },
      "checks": {
        "company": [],
        "person": ["pep_check"]
      }
    }
  }'

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

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 success field and the errors object 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.

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

Getting Started

Use Cases

Webhooks

Person

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Overview

​Endpoint

​Authentication

​Request Body

​Query Parameters

​Response

​WebSocket Events

​entity:creation-started

​entity:creation-completed

​entity:creation-failed

​Examples

​Create Company with Shareholders (Depth 1)

​Create Person (KYC) with Specific Integrations

​Create Company with Deep Hierarchy 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

​Related Endpoints

Overview

Endpoint

Authentication

Request Body

Query Parameters

Response

WebSocket Events

`entity:creation-started`

`entity:creation-completed`

`entity:creation-failed`

Examples

Create Company with Shareholders (Depth 1)

Create Person (KYC) with Specific Integrations

Create Company with Deep Hierarchy 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

Related Endpoints