Skip to main content
POST
http://api.gu1.ai
/
entities
/
automatic
Create Automatically
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>",
  "skipRulesExecution": true,
  "status": "<string>",
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {}
}
'
{
  "success": true,
  "data": {},
  "rulesResult": {}
}

​
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 integrations (checks and enrichments) automatically
This is ideal for KYC (Know Your Customer) processes where you want to onboard customers 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 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.
​
country
string
required
ISO 3166-1 alpha-2 country code (e.g., “BR”, “MX”, “AR”, “CL”)
​
type
string
required
Must be set to person
​
externalId
string
Your unique identifier for this person (optional, will be auto-generated if not provided)
​
isClient
boolean
default:"false"
Mark this person as a client/customer for tracking purposes
​
riskMatrixId
string
UUID of the risk matrix to execute rules from automatically
​
skipRulesExecution
boolean
default:"false"
Skip automatic rules execution after person creation
​
status
string
default:"under_review"
Initial status for the person
​
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)
​
autoExecuteIntegrations
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
  • 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_cpf", "bureau_credit"],
  "checks": ["pep_check", "sanctions_check"]
}
​
autoExecuteIntegrationsShareholders
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
  • executeAllActiveChecks (boolean, optional, default: false) - Execute all active checks 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
  • checks (object, optional) - Specific checks by entity type
    • company (array, default: []) - Checks for company relationships
    • person (array, default: []) - Checks for person relationships
{
  executeAllActiveEnrichments?: boolean;
  executeAllActiveChecks?: boolean;
  enrichments?: {
    company?: ValidProviderCodesEnum[];
    person?: ValidProviderCodesEnum[];
  };
  checks?: {
    company?: ValidProviderCodesEnum[];
    person?: ValidProviderCodesEnum[];
  };
}
Example:
{
  "enrichments": {
    "person": ["br_cpfcnpj_complete_person_enrichment"],
    "company": ["br_cpfcnpj_complete_company_enrichment"]
  }
}

​
Response

​
success
boolean
Indicates if the person was created successfully
​
data
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
​
rulesResult
object
Result of risk matrix execution (if configured), or null

​
Examples

​
Create Person 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": "person",
    "isClient": true,
    "autoExecuteIntegrations": {
      "executeAllActiveEnrichments": true,
      "executeAllActiveChecks": true
    }
  }'

​
Create Person 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",
    "autoExecuteIntegrations": {
      "enrichments": ["serpro_cpf", "bureau_credit"],
      "checks": ["pep_check", "sanctions_check"]
    }
  }'

​
Response Example

{
  "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",
          "nationality": "BR"
        }
      },
      "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 - Person 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 - Person Already Exists

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

​
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