Create an entity 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>",
"nationality": {},
"monitoring": {},
"externalId": "<string>",
"depth": 123,
"relationships": [
{}
],
"enrichDeclaredRelationships": true,
"isClient": true,
"registrationDate": {},
"runInBackground": true,
"workflowId": "<string>",
"riskMatrixId": [
"<string>"
],
"riskMatrixIds": [
"<string>"
],
"skipRulesExecution": true,
"status": "<string>",
"operationalHours": {},
"autoExecuteIntegrations": {},
"autoExecuteIntegrationsShareholders": {},
"customData": {},
"attributes": {}
}
'import requests
url = "http://api.gu1.ai/entities/automatic"
payload = {
"taxId": "<string>",
"country": "<string>",
"type": "<string>",
"nationality": {},
"monitoring": {},
"externalId": "<string>",
"depth": 123,
"relationships": [{}],
"enrichDeclaredRelationships": True,
"isClient": True,
"registrationDate": {},
"runInBackground": True,
"workflowId": "<string>",
"riskMatrixId": ["<string>"],
"riskMatrixIds": ["<string>"],
"skipRulesExecution": True,
"status": "<string>",
"operationalHours": {},
"autoExecuteIntegrations": {},
"autoExecuteIntegrationsShareholders": {},
"customData": {},
"attributes": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
taxId: '<string>',
country: '<string>',
type: '<string>',
nationality: {},
monitoring: {},
externalId: '<string>',
depth: 123,
relationships: [{}],
enrichDeclaredRelationships: true,
isClient: true,
registrationDate: {},
runInBackground: true,
workflowId: '<string>',
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
skipRulesExecution: true,
status: '<string>',
operationalHours: {},
autoExecuteIntegrations: {},
autoExecuteIntegrationsShareholders: {},
customData: {},
attributes: {}
})
};
fetch('http://api.gu1.ai/entities/automatic', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/entities/automatic",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'taxId' => '<string>',
'country' => '<string>',
'type' => '<string>',
'nationality' => [
],
'monitoring' => [
],
'externalId' => '<string>',
'depth' => 123,
'relationships' => [
[
]
],
'enrichDeclaredRelationships' => true,
'isClient' => true,
'registrationDate' => [
],
'runInBackground' => true,
'workflowId' => '<string>',
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'skipRulesExecution' => true,
'status' => '<string>',
'operationalHours' => [
],
'autoExecuteIntegrations' => [
],
'autoExecuteIntegrationsShareholders' => [
],
'customData' => [
],
'attributes' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/automatic"
payload := strings.NewReader("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"relationships\": [\n {}\n ],\n \"enrichDeclaredRelationships\": true,\n \"isClient\": true,\n \"registrationDate\": {},\n \"runInBackground\": true,\n \"workflowId\": \"<string>\",\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities/automatic")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"relationships\": [\n {}\n ],\n \"enrichDeclaredRelationships\": true,\n \"isClient\": true,\n \"registrationDate\": {},\n \"runInBackground\": true,\n \"workflowId\": \"<string>\",\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/automatic")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"relationships\": [\n {}\n ],\n \"enrichDeclaredRelationships\": true,\n \"isClient\": true,\n \"registrationDate\": {},\n \"runInBackground\": true,\n \"workflowId\": \"<string>\",\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {},
"rulesResult": {},
"rulesExecutionSummary": {}
}API Reference
Create an entity automatically with enrichment
Automatically create a person or company enriched from official registries in the gu1 universal entity model for KYC, KYB, and risk analysis.
POST
/
entities
/
automatic
Create an entity 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>",
"nationality": {},
"monitoring": {},
"externalId": "<string>",
"depth": 123,
"relationships": [
{}
],
"enrichDeclaredRelationships": true,
"isClient": true,
"registrationDate": {},
"runInBackground": true,
"workflowId": "<string>",
"riskMatrixId": [
"<string>"
],
"riskMatrixIds": [
"<string>"
],
"skipRulesExecution": true,
"status": "<string>",
"operationalHours": {},
"autoExecuteIntegrations": {},
"autoExecuteIntegrationsShareholders": {},
"customData": {},
"attributes": {}
}
'import requests
url = "http://api.gu1.ai/entities/automatic"
payload = {
"taxId": "<string>",
"country": "<string>",
"type": "<string>",
"nationality": {},
"monitoring": {},
"externalId": "<string>",
"depth": 123,
"relationships": [{}],
"enrichDeclaredRelationships": True,
"isClient": True,
"registrationDate": {},
"runInBackground": True,
"workflowId": "<string>",
"riskMatrixId": ["<string>"],
"riskMatrixIds": ["<string>"],
"skipRulesExecution": True,
"status": "<string>",
"operationalHours": {},
"autoExecuteIntegrations": {},
"autoExecuteIntegrationsShareholders": {},
"customData": {},
"attributes": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
taxId: '<string>',
country: '<string>',
type: '<string>',
nationality: {},
monitoring: {},
externalId: '<string>',
depth: 123,
relationships: [{}],
enrichDeclaredRelationships: true,
isClient: true,
registrationDate: {},
runInBackground: true,
workflowId: '<string>',
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
skipRulesExecution: true,
status: '<string>',
operationalHours: {},
autoExecuteIntegrations: {},
autoExecuteIntegrationsShareholders: {},
customData: {},
attributes: {}
})
};
fetch('http://api.gu1.ai/entities/automatic', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/entities/automatic",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'taxId' => '<string>',
'country' => '<string>',
'type' => '<string>',
'nationality' => [
],
'monitoring' => [
],
'externalId' => '<string>',
'depth' => 123,
'relationships' => [
[
]
],
'enrichDeclaredRelationships' => true,
'isClient' => true,
'registrationDate' => [
],
'runInBackground' => true,
'workflowId' => '<string>',
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'skipRulesExecution' => true,
'status' => '<string>',
'operationalHours' => [
],
'autoExecuteIntegrations' => [
],
'autoExecuteIntegrationsShareholders' => [
],
'customData' => [
],
'attributes' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/automatic"
payload := strings.NewReader("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"relationships\": [\n {}\n ],\n \"enrichDeclaredRelationships\": true,\n \"isClient\": true,\n \"registrationDate\": {},\n \"runInBackground\": true,\n \"workflowId\": \"<string>\",\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities/automatic")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"relationships\": [\n {}\n ],\n \"enrichDeclaredRelationships\": true,\n \"isClient\": true,\n \"registrationDate\": {},\n \"runInBackground\": true,\n \"workflowId\": \"<string>\",\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/automatic")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"relationships\": [\n {}\n ],\n \"enrichDeclaredRelationships\": true,\n \"isClient\": true,\n \"registrationDate\": {},\n \"runInBackground\": true,\n \"workflowId\": \"<string>\",\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}"
response = http.request(request)
puts response.read_body{
"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 enrichments 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
string
required
Tax identification number of the entity (CNPJ/CPF for Brazil, CUIT/CUIL for Argentina, RUT for Chile).Within an organization, an active
taxId (normalized: letters and digits only) may belong to only one entity — whether person or company. If the same type already exists, the API reuses it (alreadyExisted). If another type already holds that tax ID, the request fails with 409 and code DUPLICATE_TAX_ID.Type: string (min length: 1)string
required
ISO 3166-1 alpha-2 country code. Automatic creation supports
BR, AR, and CL only. Any other country returns an error stating automatic creation is not supported for it — use Create an entity instead.Type: string (length: 2)string
required
Type of entity to create:
company- Business entityperson- Individual person
enum - 'company' | 'person'string | null
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).
object
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.string
Your unique identifier for this entity in your system. Optional.When omitted,
externalId is set to the normalized tax ID derived from required taxId: letters and digits only, uppercase (no dots, dashes, or spaces). Example: 30-12345678-9 → 30123456789.The taxId column is still saved in the country display format. Same auto-assignment rules as Create an entity (person or company) when taxId is present.Type: string (optional)number
default:"0"
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)Brazil +
depth > 0 fails the entire request if the discovery enrichments are missing. The API checks this before creating the main entity: it does not create the person or company and then skip related records.- Person: both
br_bdc_related_companies_enrichmentandbr_bdc_related_persons_enrichmentmust be in the resolved main-entity set (autoExecuteIntegrations.enrichments, or all enabled marketplace enrichments whenexecuteAllActiveEnrichments: true). Both must be enabled for the organization.executeAllActiveEnrichments: truedoes not bypass this if either is disabled or listed inexcludeEnrichments. - Company:
br_bdc_shareholders_enrichmentmust be in that same resolved set and enabled.
depth: 0. autoExecuteIntegrationsShareholders only controls enrichments on children after they exist; it does not satisfy this check.array
Declarative links to existing entities (
relatedEntityId / relatedTaxId / relatedExternalId + relationshipType + role). Independent of enrichment depth. Max 10. Missing counterpart → RELATED_ENTITY_NOT_FOUND and the entity is not created. Same semantics as Create entity.boolean
default:"false"
When
true, after linking the counterparts in relationships, also run autoExecuteIntegrationsShareholders enrichments on those existing entities (by related entity type: company vs person lists). Independent of depth.Type: boolean (optional, default: false)boolean
default:"false"
Mark this entity as a client/customer for tracking purposesType:
boolean (default: false)string | number
Optional registration date for the main entity. ISO 8601 datetime string or epoch milliseconds.Type:
string (ISO datetime) | number (optional)boolean
default:"false"
When
true, the creation is enqueued and the API responds immediately with 202 and data.status: "processing" plus a jobId; completion is reported over Socket.IO (see WebSocket Events). When false (default), the request runs synchronously and returns the full result.Type: boolean (optional, default: false)string
UUID of an automation with trigger
create_entity_flow (or entity_created + automatic flow). When sent, the request becomes a creation-flow run: autoExecuteIntegrations, autoExecuteIntegrationsShareholders, and depth are ignored, only that automation runs (enrichments, risk matrix, conditions, and actions live in the workflow), and entity_created is not emitted. If the id is not a valid enabled create_entity_flow automation, the body flow is used instead.Type: string (uuid, optional)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).Type: string | string[] | null (optional)string[]
Preferred for multiple matrices: ordered UUID list. Takes precedence over
riskMatrixId when non-empty.Type: string[] (optional)boolean
default:"false"
Skip automatic rules execution after entity creationType:
boolean (optional, default: false)string
default:"under_review"
Initial status for the entity. Options:
activeinactivenot_startedblockedunder_review(default)pending_verification- Awaiting KYC/KYB completionawaiting_information- Waiting on client data (e.g. onboarding documents requested by email)suspendedexpireddeletedrejected
enum - 'active' | 'inactive' | 'blocked' | 'under_review' | 'pending_verification' | 'awaiting_information' | 'suspended' | 'expired' | 'deleted' | 'rejected' | 'not_started' (default: ‘under_review’)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.object
Configure automatic execution of integrations for the main entity. See Provider Codes Reference for available codes.Type: Example:Do not enable a catalog fallback in Marketplace (and do not list it here) if you only want it when the primary fails. See Marketplace fallbacks.
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). If the code is the basic-data source that would run (enabled primary or substitute), that creation skips it and uses the next chain member that is enabled and not excluded.
{
executeAllActiveEnrichments?: boolean; // default: false
enrichments?: ValidProviderCodesEnum[]; // default: []
enrichmentGroupRefs?: string[];
excludeEnrichments?: ValidProviderCodesEnum[]; // default: []
}
{
"executeAllActiveEnrichments": true,
"excludeEnrichments": ["br_bdc_shareholders_enrichment"],
"enrichmentGroupRefs": ["my_marketplace_group_slug"]
}
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: 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. This also skips basic data for those related entities when the excluded code is the one that would run.
{
executeAllActiveEnrichments?: boolean; // default: false
enrichments?: {
company?: ValidProviderCodesEnum[]; // default: []
person?: ValidProviderCodesEnum[]; // default: []
};
enrichmentGroupRefs?: string[];
excludeEnrichments?: ValidProviderCodesEnum[]; // default: []
}
{
"executeAllActiveEnrichments": true,
"excludeEnrichments": ["br_bdc_shareholders_enrichment"],
"enrichmentGroupRefs": ["shareholder_pipeline_group_slug"]
}
Required Enrichment Codes by Country
Automatic creation needs at least one basic-data enrichment enabled in Marketplace for that country and entity type (company or person). The canonical primary runs first when it is active and not listed in
excludeEnrichments. If it is off or excluded, the first substitute in its chain that is enabled and not excluded runs instead. If none of the chain is available, the request fails before the entity is created.executeAllActiveEnrichments: true only includes enrichments that are enabled. A disabled substitute does not count as a basic-data source. When the primary is active and fails, a substitute may still run with its card off if the catalog has fallback_requires_activation: false. That does not replace the requirement to have one of them enabled in order to start.When the whole chain is missing, the response is HTTP 422 with A person in Brazil uses the same sentence with
success: false and error.code BASIC_DATA_ENRICHMENT_REQUIRED. The text in error.message and data.errors.creationFailed[].error is the same string as the API log (English, truncated at 500 characters). It is not the generic lookup message (We could not complete the basic data lookup for this document.). The text names the codes to activate, in catalog-chain order.{
"success": false,
"error": {
"code": "BASIC_DATA_ENRICHMENT_REQUIRED",
"message": "Automatic creation requires at least one active basic-data enrichment for BR company. Activate one of: br_cpfcnpj_complete_company_enrichment, br_brasilapi_company_enrichment, br_cnpjws_company_enrichment, br_opencnpj_company_enrichment, br_bdc_basic_data_company_enrichment (marketplace)."
},
"data": {
"entity": null,
"errors": {
"creationFailed": [
{
"entityType": "company",
"level": 0,
"code": "BASIC_DATA_ENRICHMENT_REQUIRED",
"error": "Automatic creation requires at least one active basic-data enrichment for BR company. Activate one of: br_cpfcnpj_complete_company_enrichment, br_brasilapi_company_enrichment, br_cnpjws_company_enrichment, br_opencnpj_company_enrichment, br_bdc_basic_data_company_enrichment (marketplace)."
}
]
}
}
}
BR person and the person codes in the table below. Argentina and Chile use the same sentence with their own chain. Bulk import in automatic mode stores that same text on the failed row.Brazil (BR)
Main Entity
| Entity Type | Primary (runs first when active) | Also accepted, in this order, when enabled |
|---|---|---|
| Company | br_cpfcnpj_complete_company_enrichment | br_brasilapi_company_enrichment, br_cnpjws_company_enrichment, br_opencnpj_company_enrichment, br_bdc_basic_data_company_enrichment |
| Person | br_bdc_basic_data_enrichment | br_cpfcnpj_complete_person_enrichment, br_cpfcnpj_complete_person_9_enrichment |
Shareholders / Related Entities (only when depth > 0)
| Main Entity Type | Required Enrichment Code(s) | Description |
|---|---|---|
| Company | br_bdc_shareholders_enrichment | Required to discover the QSA. Missing → the whole request fails; the company is not created. |
| Person | br_bdc_related_companies_enrichment AND br_bdc_related_persons_enrichment | Both required. If either is missing, disabled, or excluded → the whole request fails; the person is not created. |
These codes must be on the main entity resolved set, not only on
autoExecuteIntegrationsShareholders. Missing either related-person enrichment (or shareholders for companies) is a hard fail, not a partial create.The API runs those enrichments on the main entity to discover shareholders or related people/companies.
autoExecuteIntegrationsShareholders only controls what runs on each child after it is created.Argentina (AR)
Main Entity
| Entity Type | Primary (runs first when active) | Also accepted when enabled |
|---|---|---|
| Company and Person | ar_nosis_extended_verification_enrichment | ar_arca_contribuyente_enrichment (one way only: ARCA does not fall back to the primary) |
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.Chile (CL)
Main Entity
| Entity Type | Primary (only code in the chain) | Catalog substitutes |
|---|---|---|
| Company | cl_rutsinfo_info_company_enrichment | None. If it is off, automatic company creation fails. |
| Person | cl_baseapi_basic_data_person_enrichment | None. If it is off, automatic person creation fails. |
Shareholders / Related Entities
Chile does not support automatic shareholder/relationship creation yet. The
depth parameter must be 0. If depth > 0 is provided, the request fails.object
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 (optional; closed enum: M, F, male, female, other, unknown — use other for non-binary; in AR, only M/F apply to CUIL derivation and RENAPER. See Create entity — Person) |
name, email, phone, birthDate (person), address (string or object with fullAddress, street, city, …), gender (optional enum — other for non-binary).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):{
"taxId": "23450679909",
"country": "AR",
"type": "person",
"customData": {
"name": "JOHN DOE",
"email": "client@company.com",
"phone": "+541112345678",
"birthDate": "1990-05-15",
"address": "123 Main St, Buenos Aires"
}
}
{
"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"
}
}
}
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
boolean
default:"false"
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
POST http://api.gu1.ai/entities/automatic?refresh=true
boolean
default:"false"
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
POST http://api.gu1.ai/entities/automatic?reEnrichExistingChildEntities=true&depth=3
- 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
By default the endpoint executes synchronously and returns the complete result including the main entity and all related entities created. WithrunInBackground: true the response is 202 and the work continues in the background:
{
"success": true,
"data": { "status": "processing", "jobId": "...", "taxId": "...", "type": "company" }
}
boolean
Indicates if the entity was created successfully
object
Complete information about the creation:
entity(object) - The main entity created with all its datashareholders(array) - Child entities materialized in that run (companies only). Each item is{ id, name, taxId, type }. Percentage and roles are stored on the relationship; read them later with Get materialized shareholders.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) - Extra enrichments that failed after the entity was persisted (entityId+failedProviders). Empty when basic-data fails and the entity is not created. EachfailedProvidersitem hasproviderCode,error(English), and optionalcode. When the request asked for an enrichment the organization has not enabled,codeisINTEGRATION_NOT_ENABLED(alsoINTEGRATION_NOT_CONFIGURED,INTEGRATION_BLOCKED,INTEGRATION_GLOBALLY_DISABLED,CONTRACT_ACCESS_NOT_INCLUDED,INTEGRATION_NOT_FOUND). Those codes are not retried. Other enrichments in the same request still run, andsuccessstaystruewhen the entity was created.enrichmentFailedDetails(array, additive) - Each basic-data attempt that failed (primary + catalog fallbacks) when the entity was not created. Items:providerCode(marketplace code),code(semantic, e.g.DOCUMENT_RESTRICTED,UPSTREAM_CREDITS_ERROR),errorMessage(English). Also nested on the matchingcreationFailed[]row.
Person <taxId> with attributes.isMinor: true. Retries, fallbacks, and additional enrichments are skipped; risk analysis runs normally. This behavior is disabled by default.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.
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
shadowstatus.
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"
}
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.
{
"taxId": "30-71000001-2",
"country": "AR",
"type": "company",
"depth": 1,
"monitoring": {
"main": {
"global_gueno_sanctions_enrichment": {
"watchlist": true
}
},
"relationships": {
"global_gueno_sanctions_enrichment": {
"watchlist": true,
"riskMatrixId": null
}
}
},
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_afip_registration_enrichment",
"global_gueno_sanctions_enrichment"
]
},
"autoExecuteIntegrationsShareholders": {
"executeAllActiveEnrichments": false,
"enrichments": {
"company": ["global_gueno_sanctions_enrichment"],
"person": ["global_gueno_sanctions_enrichment"]
}
}
}
ar_afip_registration_enrichment) ignore monitoring and always run as one-off queries.
This payload only illustrates
monitoring and Gu1 enrichment codes. A real request must still include the mandatory registry enrichments for the chosen country and type (see Required Enrichment Codes by Country above), or automatic creation will fail.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,
}
}'
const response = await fetch('http://api.gu1.ai/entities/automatic', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
taxId: '12.345.678/0001-90',
country: 'BR',
type: 'company',
depth: 1,
isClient: true,
autoExecuteIntegrations: {
executeAllActiveEnrichments: true,
}
})
});
const data = await response.json();
console.log(data);
// Listen for WebSocket events
socket.on('entity:creation-completed', (result) => {
console.log('Entity created:', result.mainEntity);
console.log('Total entities created:', result.stats.totalEntitiesCreated);
});
import requests
response = requests.post(
'http://api.gu1.ai/entities/automatic',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'taxId': '12.345.678/0001-90',
'country': 'BR',
'type': 'company',
'depth': 1,
'isClient': True,
'autoExecuteIntegrations': {
'executeAllActiveEnrichments': True,
}
}
)
data = response.json()
print(data)
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": ["br_bdc_basic_data_enrichment"]
}
}'
const response = await fetch('http://api.gu1.ai/entities/automatic', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
taxId: '123.456.789-00',
country: 'BR',
type: 'person',
externalId: 'customer_12345',
depth: 0,
autoExecuteIntegrations: {
enrichments: ['br_bdc_basic_data_enrichment']
}
})
});
const data = await response.json();
import requests
response = requests.post(
'http://api.gu1.ai/entities/automatic',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'taxId': '123.456.789-00',
'country': 'BR',
'type': 'person',
'externalId': 'customer_12345',
'depth': 0,
'autoExecuteIntegrations': {
'enrichments': ['br_bdc_basic_data_enrichment']
}
}
)
data = response.json()
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"],
"enrichmentGroupRefs": ["main_entity_group_slug"]
},
"autoExecuteIntegrationsShareholders": {
"enrichments": {
"company": ["br_cpfcnpj_complete_company_enrichment"],
"person": ["br_bdc_basic_data_enrichment"]
},
"enrichmentGroupRefs": ["child_entities_group_slug"]
}
}'
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",
"cnae": "6202-3/00",
"cnaeDescription": "Development and licensing of customizable computer programs",
"industry": "Development and licensing of customizable computer programs"
}
},
"createdAt": "2024-12-23T10:30:00.000Z",
"updatedAt": "2024-12-23T10:30:00.000Z"
},
"shareholders": [
{
"id": "shareholder_1_uuid",
"name": "João Silva",
"taxId": "12345678900",
"type": "person"
},
{
"id": "shareholder_2_uuid",
"name": "Maria Santos",
"taxId": "98765432100",
"type": "person"
}
],
"summary": {
"entitiesCreated": 3,
"relationshipsCreated": 2,
"errorsCount": 0
}
},
"rulesResult": null
}
entityData.company.cnae and cnaeDescription contain the
main economic activity from the normalized basic-data result. industry contains the
same activity description for compatibility with existing entity profiles.
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
Returned when the normalizedtaxId is already used by an active entity of a different type in the same organization (person vs company). Same-type matches are reused instead of failing.
{
"success": false,
"error": {
"code": "DUPLICATE_TAX_ID",
"message": "This tax ID is already registered for a company in this organization (Entity ID: uuid).",
"details": {
"existingEntityId": "uuid",
"existingEntityType": "company"
}
}
}
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
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
Was this page helpful?