Create a company automatically with enrichment

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>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "operationalHours": {},
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "customData": {},
  "attributes": {}
}
'

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

POST

entities

automatic

Create a company automatically with enrichment

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>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "operationalHours": {},
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "customData": {},
  "attributes": {}
}
'

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

Overview

The automatic company creation endpoint allows you to create companies by providing minimal information (tax ID and country). The system automatically:

Fetches company data from official registries
Enriches the company with additional information
Executes enrichments automatically

This is ideal for KYB (Know Your Business) processes where you want to onboard businesses 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 company (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.

country

string

required

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

type

string

required

Must be set to company

externalId

string

Your unique identifier for this company (optional, will be auto-generated if not provided)

isClient

boolean

default:"false"

Mark this company as a client/business for tracking purposes

riskMatrixId

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).

riskMatrixIds

string[]

Preferred for multiple matrices: ordered UUID list. Takes precedence over riskMatrixId when non-empty.

skipRulesExecution

boolean

default:"false"

Skip automatic rules execution after company creation

status

string

default:"under_review"

Initial status for the company

operationalHours

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.

depth

number

default:"0"

Depth of relationship extraction (0-5). Controls how many levels of shareholders/relationships to automatically fetch and create.

0: No relationships (only main entity)
1: Direct shareholders only
2: Shareholders + their shareholders
3-5: Additional levels (use with caution - can create many entities)

autoExecuteIntegrations

object

Configure automatic execution of integrations for the main company 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.

{
  executeAllActiveEnrichments?: boolean; // default: false
  enrichments?: ValidProviderCodesEnum[]; // default: []
  enrichmentGroupRefs?: string[];
}

Example:

{
  "executeAllActiveEnrichments": false,
  "enrichments": ["br_cpfcnpj_complete_company_enrichment", "br_bdc_shareholders_enrichment"],
  "enrichmentGroupRefs": ["my_marketplace_group_slug"],
}

autoExecuteIntegrationsShareholders

object

Configure automatic execution of integrations for discovered shareholders/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 shareholders
enrichments (object, optional) - Specific enrichments by entity type
- company (array, default: []) - Enrichments for company shareholders
- person (array, default: []) - Enrichments for person shareholders
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.

{
  executeAllActiveEnrichments?: boolean;
  enrichments?: {
    company?: ValidProviderCodesEnum[];
    person?: ValidProviderCodesEnum[];
  };
  enrichmentGroupRefs?: string[];
}

Example:

{
  "enrichments": {
    "person": [
      "br_cpfcnpj_complete_person_enrichment",
      "global_complyadvantage_person_search_enrichment"
    ],
    "company": ["br_cpfcnpj_complete_company_enrichment"]
  },
  "enrichmentGroupRefs": ["shareholder_pipeline_group_slug"]
}

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 company data from official registries and the request will fail.

Brazil (BR)

Scenario	Required Enrichment Code(s)	Description
Main entity	`br_cpfcnpj_complete_company_enrichment`	Fetches company data from CNPJ/Receita Federal (legal name, trade name, address, industry, etc.)
Shareholders (`depth > 0`)	`br_bdc_shareholders_enrichment`	Required in `autoExecuteIntegrations.enrichments`. Fetches the QSA (Quadro Societário) to discover company shareholders and directors

The shareholder enrichment must be included in the main entity’s autoExecuteIntegrations.enrichments array (not in autoExecuteIntegrationsShareholders), because the system needs to run it on the main company to discover the QSA. The autoExecuteIntegrationsShareholders field controls what enrichments to run on each shareholder after they are created.

Argentina (AR)

Scenario	Required Enrichment Code	Description
Main entity	`ar_nosis_extended_verification_enrichment`	Fetches company data from Nosis (legal name, CUIT status, address, activities, etc.)

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

customData

object

Optional — Client values for the main company that must not be replaced by enrichments. Full reference: Automatic entity creation.Fields: name, email, phone, address → entityData.company.address (birthDate is not used for companies).Example:

{
  "taxId": "30712345678",
  "country": "AR",
  "type": "company",
  "customData": {
    "name": "Acme Argentina S.A. (trade name)",
    "email": "contact@acme.com",
    "phone": "+541140000000",
    "address": { "fullAddress": "Av. del Libertador 100, Buenos Aires", "city": "Buenos Aires" }
  }
}

attributes

object

Optional - Custom attributes as key-value pairs for the created entity.Applied only to the main entity (the 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"]
}

Response

success

boolean

Indicates if the company was created successfully

data

object

Complete information about the creation:

entity (object) - The company created with all data
summary (object) - Creation summary
errors (object, optional) - Details of any errors

rulesResult

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.

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, 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 Company with All Active 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": "company",
    "isClient": true,
    "autoExecuteIntegrations": {
      "executeAllActiveEnrichments": true,
    }
  }'

Create Company 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": "company",
    "externalId": "business_12345",
    "autoExecuteIntegrations": {
      "enrichments": ["br_cpfcnpj_complete_company_enrichment"],
    }
  }'

Response Example

{
  "success": true,
  "data": {
    "entity": {
      "id": "company_uuid",
      "organizationId": "org_uuid",
      "type": "company",
      "name": "Tech Solutions LTDA",
      "taxId": "12345678900",
      "countryCode": "BR",
      "status": "under_review",
      "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"
    },
    "summary": {
      "entitiesCreated": 1,
      "relationshipsCreated": 0,
      "errorsCount": 0
    }
  },
  "rulesResult": null
}

Error Responses

400 Bad Request - Invalid Tax ID

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

404 Not Found - Company Not Found in Registry

{
  "success": false,
  "error": "Entity not found in official registry",
  "details": {
    "taxId": "123.456.789-00",
    "country": "BR",
    "registry": "Receita Federal"
  }
}

409 Conflict - Company Already Exists

{
  "success": false,
  "error": "Entity with this tax ID already exists",
  "details": {
    "existingEntityId": "uuid",
    "taxId": "123.456.789-00"
  }
}

Best Practices

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

Next Steps

Get Company - Retrieve company details
Create Company Manually - Create companies with your own data
Create KYB Validation - Start identity verification

Create a company entity Get a company by ID

⌘I

​Overview

​Endpoint

​Authentication

​Request Body

​Required Enrichment Codes by Country

​Brazil (BR)

​Argentina (AR)

​Response

​Examples

​Create Company with All Active Integrations

​Create Company with Specific Integrations

​Response Example

​Error Responses

​400 Bad Request - Invalid Tax ID

​404 Not Found - Company Not Found in Registry

​409 Conflict - Company Already Exists

​Best Practices

​Next Steps

Overview

Endpoint

Authentication

Request Body

Required Enrichment Codes by Country

Brazil (BR)

Argentina (AR)

Response

Examples

Create Company with All Active Integrations

Create Company with Specific Integrations

Response Example

Error Responses

400 Bad Request - Invalid Tax ID

404 Not Found - Company Not Found in Registry

409 Conflict - Company Already Exists

Best Practices

Next Steps