Create a person 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": {}
}
'import requests
url = "http://api.gu1.ai/entities/automatic"
payload = {
"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": {}
}
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>',
externalId: '<string>',
isClient: true,
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
skipRulesExecution: true,
status: '<string>',
operationalHours: {},
depth: 123,
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>',
'externalId' => '<string>',
'isClient' => true,
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'skipRulesExecution' => true,
'status' => '<string>',
'operationalHours' => [
],
'depth' => 123,
'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 \"externalId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"depth\": 123,\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 \"externalId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"depth\": 123,\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 \"externalId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"depth\": 123,\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 a person automatically with enrichment
Automatically create person with enriched data from registries β for person entities in the gu1 KYC and risk analysis platform, with examples for create.
POST
/
entities
/
automatic
Create a person 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": {}
}
'import requests
url = "http://api.gu1.ai/entities/automatic"
payload = {
"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": {}
}
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>',
externalId: '<string>',
isClient: true,
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
skipRulesExecution: true,
status: '<string>',
operationalHours: {},
depth: 123,
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>',
'externalId' => '<string>',
'isClient' => true,
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'skipRulesExecution' => true,
'status' => '<string>',
'operationalHours' => [
],
'depth' => 123,
'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 \"externalId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"depth\": 123,\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 \"externalId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"depth\": 123,\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 \"externalId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"depth\": 123,\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 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 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 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.
string
required
ISO 3166-1 alpha-2 country code (e.g., βBRβ, βMXβ, βARβ, βCLβ)
string
required
Must be set to
personstring
Your unique identifier for this person (optional, will be auto-generated if not provided)
boolean
default:"false"
Mark this person as a client/customer for tracking purposes
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).string[]
Preferred for multiple matrices: ordered UUID list. Takes precedence over
riskMatrixId when non-empty.boolean
default:"false"
Skip automatic rules execution after person creation
string
default:"under_review"
Initial status. Default
under_review. Optional: not_started, active, inactive, blocked, under_review, pending_verification, awaiting_information, suspended, expired, deleted, rejected. See Entities overview β Entity Status.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.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 only2: Relationships + their relationships3-5: Additional levels (use with caution - can create many entities)
object
Configure automatic execution of integrations for the main person entity. See Provider Codes Reference for available codes.Type: Example:
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.
{
executeAllActiveEnrichments?: boolean; // default: false
enrichments?: ValidProviderCodesEnum[]; // default: []
enrichmentGroupRefs?: string[];
}
{
"executeAllActiveEnrichments": false,
"enrichments": ["br_bdc_basic_data_enrichment"],
"enrichmentGroupRefs": ["my_marketplace_group_slug"],
}
object
Configure automatic execution of integrations for discovered relationships. Useful when using Example:
depth > 0. See Provider Codes Reference for available codes.Type: object (optional)Properties:executeAllActiveEnrichments(boolean, optional, default:false) - Execute all active enrichments on related entitiesenrichments(object, optional) - Specific enrichments by entity typecompany(array, default:[]) - Enrichments for company relationshipsperson(array, default:[]) - Enrichments for person relationships
enrichmentGroupRefs(array of strings, optional) - Same slugs as on the main object; applied to bothcompanyandpersonwhenexecuteAllActiveEnrichmentsisfalse. WhenexecuteAllActiveEnrichmentsistrueon this object, group refs are ignored; explicit per-typeenrichmentsmay still append after each sideβs active set.
{
executeAllActiveEnrichments?: boolean;
enrichments?: {
company?: ValidProviderCodesEnum[];
person?: ValidProviderCodesEnum[];
};
enrichmentGroupRefs?: string[];
}
{
"enrichments": {
"person": ["br_cpfcnpj_complete_person_enrichment"],
"company": ["br_cpfcnpj_complete_company_enrichment"]
},
"enrichmentGroupRefs": ["related_entities_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 person data from official registries and the request will fail.Brazil (BR)
| Scenario | Required Enrichment Code(s) | Description |
|---|---|---|
| Main entity | br_bdc_basic_data_enrichment | Fetches person data via BDC/CPF (full name, date of birth, address, etc.) |
Relationships (depth > 0) | br_bdc_related_companies_enrichment AND br_bdc_related_persons_enrichment | Both required in autoExecuteIntegrations.enrichments. Fetches companies and persons related to the individual |
The relationship 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 person to discover the relationships. The autoExecuteIntegrationsShareholders field controls what enrichments to run on each related entity after they are created.Argentina (AR)
| Scenario | Required Enrichment Code | Description |
|---|---|---|
| Main entity | ar_nosis_extended_verification_enrichment | Fetches person data from Nosis |
Argentina does not support automatic relationship creation yet. The
depth parameter must be 0.object
Optional β Client values for the main person that must not be replaced by enrichments. Full reference (root vs
entityData): Automatic entity creation.Fields: name, email, phone, birthDate β entityData.person.dateOfBirth, address β entityData.person.address, gender (enum: M | F | male | female | other | unknown β use other for non-binary; see Create entity).Example:{
"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"
}
}
object
Optional - Custom attributes as key-value pairs for the created entity.Applied only to the main entity (the person created), not to relationships/shareholders. 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
boolean
Indicates if the person was created successfully
object
Complete information about the creation:
entity(object) - The person created with all datasummary(object) - Creation summaryerrors(object, optional) - Details of any errors
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, 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.
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,
}
}'
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',
isClient: true,
autoExecuteIntegrations: {
executeAllActiveEnrichments: true,
}
})
});
const data = await response.json();
console.log('Person created:', data.data.entity);
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',
'isClient': True,
'autoExecuteIntegrations': {
'executeAllActiveEnrichments': True,
}
}
)
data = response.json()
print('Person created:', data['data']['entity'])
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": ["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',
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',
'autoExecuteIntegrations': {
'enrichments': ['br_bdc_basic_data_enrichment']
}
}
)
data = response.json()
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
- Error handling: Always check the
successfield in the response - Rate limiting: Be mindful of rate limits when creating multiple persons
- Integration selection: Choose specific integrations for better control over cost and performance
Next Steps
- Get Person - Retrieve person details
- Create Person Manually - Create persons with your own data
- Create KYC Validation - Start identity verification
Was this page helpful?