Crear una entidad persona
curl --request POST \
--url http://api.gu1.ai/entities \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "<string>",
"externalId": "<string>",
"name": "<string>",
"countryCode": "<string>",
"taxId": "<string>",
"operationalHours": {},
"attributes": {},
"entityData": {},
"registrationDate": "<string>",
"isClient": true,
"riskMatrixId": [
"<string>"
],
"riskMatrixIds": [
"<string>"
],
"skipRulesExecution": true,
"status": "<string>",
"autoExecuteIntegrations": {},
"monitoring": {}
}
'import requests
url = "http://api.gu1.ai/entities"
payload = {
"type": "<string>",
"externalId": "<string>",
"name": "<string>",
"countryCode": "<string>",
"taxId": "<string>",
"operationalHours": {},
"attributes": {},
"entityData": {},
"registrationDate": "<string>",
"isClient": True,
"riskMatrixId": ["<string>"],
"riskMatrixIds": ["<string>"],
"skipRulesExecution": True,
"status": "<string>",
"autoExecuteIntegrations": {},
"monitoring": {}
}
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({
type: '<string>',
externalId: '<string>',
name: '<string>',
countryCode: '<string>',
taxId: '<string>',
operationalHours: {},
attributes: {},
entityData: {},
registrationDate: '<string>',
isClient: true,
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
skipRulesExecution: true,
status: '<string>',
autoExecuteIntegrations: {},
monitoring: {}
})
};
fetch('http://api.gu1.ai/entities', 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",
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([
'type' => '<string>',
'externalId' => '<string>',
'name' => '<string>',
'countryCode' => '<string>',
'taxId' => '<string>',
'operationalHours' => [
],
'attributes' => [
],
'entityData' => [
],
'registrationDate' => '<string>',
'isClient' => true,
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'skipRulesExecution' => true,
'status' => '<string>',
'autoExecuteIntegrations' => [
],
'monitoring' => [
]
]),
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"
payload := strings.NewReader("{\n \"type\": \"<string>\",\n \"externalId\": \"<string>\",\n \"name\": \"<string>\",\n \"countryCode\": \"<string>\",\n \"taxId\": \"<string>\",\n \"operationalHours\": {},\n \"attributes\": {},\n \"entityData\": {},\n \"registrationDate\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"autoExecuteIntegrations\": {},\n \"monitoring\": {}\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")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"<string>\",\n \"externalId\": \"<string>\",\n \"name\": \"<string>\",\n \"countryCode\": \"<string>\",\n \"taxId\": \"<string>\",\n \"operationalHours\": {},\n \"attributes\": {},\n \"entityData\": {},\n \"registrationDate\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"autoExecuteIntegrations\": {},\n \"monitoring\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities")
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 \"type\": \"<string>\",\n \"externalId\": \"<string>\",\n \"name\": \"<string>\",\n \"countryCode\": \"<string>\",\n \"taxId\": \"<string>\",\n \"operationalHours\": {},\n \"attributes\": {},\n \"entityData\": {},\n \"registrationDate\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"autoExecuteIntegrations\": {},\n \"monitoring\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"entity": {},
"rulesResult": {},
"rulesExecutionSummary": {}
}Referencia API
Crear una entidad persona
Crear una nueva persona con datos personalizados — para entidades de persona en la plataforma KYC y análisis de riesgo gu1, con ejemplos para create.
POST
/
entities
Crear una entidad persona
curl --request POST \
--url http://api.gu1.ai/entities \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "<string>",
"externalId": "<string>",
"name": "<string>",
"countryCode": "<string>",
"taxId": "<string>",
"operationalHours": {},
"attributes": {},
"entityData": {},
"registrationDate": "<string>",
"isClient": true,
"riskMatrixId": [
"<string>"
],
"riskMatrixIds": [
"<string>"
],
"skipRulesExecution": true,
"status": "<string>",
"autoExecuteIntegrations": {},
"monitoring": {}
}
'import requests
url = "http://api.gu1.ai/entities"
payload = {
"type": "<string>",
"externalId": "<string>",
"name": "<string>",
"countryCode": "<string>",
"taxId": "<string>",
"operationalHours": {},
"attributes": {},
"entityData": {},
"registrationDate": "<string>",
"isClient": True,
"riskMatrixId": ["<string>"],
"riskMatrixIds": ["<string>"],
"skipRulesExecution": True,
"status": "<string>",
"autoExecuteIntegrations": {},
"monitoring": {}
}
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({
type: '<string>',
externalId: '<string>',
name: '<string>',
countryCode: '<string>',
taxId: '<string>',
operationalHours: {},
attributes: {},
entityData: {},
registrationDate: '<string>',
isClient: true,
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
skipRulesExecution: true,
status: '<string>',
autoExecuteIntegrations: {},
monitoring: {}
})
};
fetch('http://api.gu1.ai/entities', 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",
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([
'type' => '<string>',
'externalId' => '<string>',
'name' => '<string>',
'countryCode' => '<string>',
'taxId' => '<string>',
'operationalHours' => [
],
'attributes' => [
],
'entityData' => [
],
'registrationDate' => '<string>',
'isClient' => true,
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'skipRulesExecution' => true,
'status' => '<string>',
'autoExecuteIntegrations' => [
],
'monitoring' => [
]
]),
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"
payload := strings.NewReader("{\n \"type\": \"<string>\",\n \"externalId\": \"<string>\",\n \"name\": \"<string>\",\n \"countryCode\": \"<string>\",\n \"taxId\": \"<string>\",\n \"operationalHours\": {},\n \"attributes\": {},\n \"entityData\": {},\n \"registrationDate\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"autoExecuteIntegrations\": {},\n \"monitoring\": {}\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")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"<string>\",\n \"externalId\": \"<string>\",\n \"name\": \"<string>\",\n \"countryCode\": \"<string>\",\n \"taxId\": \"<string>\",\n \"operationalHours\": {},\n \"attributes\": {},\n \"entityData\": {},\n \"registrationDate\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"autoExecuteIntegrations\": {},\n \"monitoring\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities")
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 \"type\": \"<string>\",\n \"externalId\": \"<string>\",\n \"name\": \"<string>\",\n \"countryCode\": \"<string>\",\n \"taxId\": \"<string>\",\n \"operationalHours\": {},\n \"attributes\": {},\n \"entityData\": {},\n \"registrationDate\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"autoExecuteIntegrations\": {},\n \"monitoring\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"entity": {},
"rulesResult": {},
"rulesExecutionSummary": {}
}Resumen
Crea una nueva entidad de persona con los atributos especificados. Las entidades de persona representan clientes individuales que deseas analizar para riesgo y cumplimiento (KYC).Endpoint
POST http://api.gu1.ai/entities
Autenticación
Requiere una clave API válida en el encabezado Authorization:Authorization: Bearer YOUR_API_KEY
Cuerpo de la Solicitud
string
required
Debe ser
person para crear una entidad de personastring
required
Tu identificador único para esta persona en tu sistema
string
required
Nombre para mostrar de la persona
string
required
Código de país ISO 3166-1 alpha-2 (ej., “US”, “BR”, “AR”)
string
Número de identificación fiscal (validado según el país)
📋 Ver Formatos de Tax ID por País para formatos aceptados y reglas de validación para cada país.
object | null
Horario operativo opcional en raíz (persona o empresa) para reglas KYT (
outside_entity_operational_hours / inside_entity_operational_hours en transactedAt). Misma forma que en Crear entidad: timezone + weekly (monday…sunday, start/end o closed). Valores de timezone: Enum zona horaria.object
Opcional - Atributos personalizados como pares clave-valor para metadatos flexiblesÚsalo para campos personalizados que no encajan en el esquema estándar (ej: IDs internos, etiquetas, banderas)
object
Opcional - Estructura de datos específica de persona (ver más abajo)
¿Cuándo usar entityData?Ejemplo Completo (con datos KYC):
- Opcional para creación básica de entidad - Puedes crear una persona con solo
type,name,taxIdycountryCode - Requerido para enriquecimiento y análisis de riesgo - Si quieres ejecutar verificaciones de cumplimiento, necesitarás proporcionar campos relevantes
- Puede ser completado después - Puedes crear una persona mínima primero, luego actualizarla con datos completos antes de ejecutar análisis de riesgo
{
"type": "person",
"name": "Juan Pérez",
"taxId": "12345678",
"countryCode": "ES"
// No se necesita entityData para creación básica
}
{
"type": "person",
"name": "Juan Pérez",
"taxId": "12345678",
"countryCode": "ES",
"entityData": {
"person": {
"firstName": "Juan",
"lastName": "Pérez",
"dateOfBirth": "1980-01-15",
"email": "juan@example.com",
"phone": "+34612345678"
}
}
}
string
Fecha de registro de la persona en formato ISO 8601 datetime (ej., “2024-01-15T10:30:00Z”)
boolean
default:"false"
Marca esta persona como cliente para fines de seguimiento
string | string[]
Uno o más UUIDs de matrices de riesgo (legacy: un solo UUID). Si se envían, tras la creación el sistema evalúa la persona solo contra reglas activas de esas matrices (salvo
skipRulesExecution: true). Misma semántica que riskMatrixIds cuando enviás un único id como string. Ver Ejecución de Matriz de Riesgo abajo.string[]
Forma preferida para varias matrices: lista ordenada de UUIDs de tu organización. Si viene informada y no vacía, tiene precedencia sobre
riskMatrixId.boolean
default:"false"
Omitir la ejecución automática de reglas después de crear la persona. Use esto para crear la entidad primero y activar las reglas manualmente más tarde.
string
default:"under_review"
Estado inicial de la persona. Opciones:
active- Persona activainactive- Persona inactivanot_started- Análisis aún no iniciado (estado inicial opcional; el default sigue siendounder_review)blocked- Persona bloqueadaunder_review- Persona en revisión (predeterminado)pending_verification- Esperando completar KYC/KYBawaiting_information- Esperando datos del cliente (p. ej. documentos de onboarding pedidos por correo)suspended- Persona suspendidaexpired- Registro de persona expiradodeleted- Eliminación lógicarejected- Persona rechazada
object
Configurar la ejecución automática de enriquecimientos al crear la persona.Estructura:Propiedades:
{
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_renaper_data_enrichment",
"ar_repet_person_enrichment",
"global_gueno_sanctions_enrichment"
],
"excludeEnrichments": []
}
executeAllActiveEnrichments(boolean) - Ejecutar todos los enriquecimientos activos de la organizaciónenrichments(string[]) - Códigos de enriquecimiento a ejecutar tras crear la entidadenrichmentGroupRefs(string[], opcional) - Slugs de grupos del MarketplaceexcludeEnrichments(string[], opcional) - Códigos a omitir del conjunto final
*_check ya no forman parte del contrato de creación; si los enviás en payloads legacy, se ignoran al parsear.Ver Códigos de proveedores y Crear entidad.object
Opcional. Solo afecta enriquecimientos que admiten monitoreo continuo (hoy:
global_gueno_sanctions_enrichment). Misma semántica que Crear entidad — monitoreo: monitoring.main[código] con { "watchlist": true } (o true legacy), el código en enrichments, y monitoreo habilitado en Marketplace.Monitoreo de sanciones Gu1 (persona)
{
"type": "person",
"externalId": "cust_screening_001",
"name": "María González",
"countryCode": "AR",
"taxId": "27-12345678-1",
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15",
"nationality": "AR"
}
},
"monitoring": {
"main": {
"global_gueno_sanctions_enrichment": {
"watchlist": true
}
}
},
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": ["global_gueno_sanctions_enrichment"]
}
}
Estructura de Datos de Entidad de Persona
El objetoentityData.person debe contener:
{
"person": {
"firstName": "string",
"lastName": "string",
"dateOfBirth": "YYYY-MM-DD",
"nationality": "string",
"occupation": "string",
"income": number,
"incomeCurrency": "string",
"address": "string | object (ver nota de Formato de Dirección)",
"city": "string",
"state": "string",
"country": "string",
"postalCode": "string",
"email": "string",
"phone": "string",
"alternativePhone": "string",
"idType": "national_id | passport | drivers_license | tax_id | other",
"idNumber": "string",
"isPep": boolean,
"pepPosition": "string",
"pepCountry": "string"
}
}
Formato de Dirección: El campo
address admite ambos formatos:- Formato de cadena (simple):
"Av. Paulista, 1000, São Paulo, SP, Brazil" - Formato de objeto (estructurado):
{ "street": "Av. Paulista", "number": "1000", "complement": "Suite 200", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "country": "Brazil", "postalCode": "01310-100" }
Ejecución de Matriz de Riesgo
Puede ejecutar automáticamente una o más matrices de riesgo (reglas de cumplimiento KYC) al crear una persona proporcionandoriskMatrixId o riskMatrixIds.
Cómo funciona
- Obtenga su(s) ID(s) de Matriz de Riesgo desde el panel de gu1 (formato: UUID)
- Incluya
riskMatrixIdoriskMatrixIdsen su solicitud de creación - El sistema automáticamente:
- Crea la entidad persona
- Ejecuta todas las reglas KYC en la matriz
- Calcula el puntaje de riesgo
- Genera alertas de cumplimiento si es necesario
- Actualiza el estado de la persona según los resultados
Ejemplo con Matriz de Riesgo
{
"type": "person",
"name": "María González",
"taxId": "20-12345678-9",
"countryCode": "AR",
"riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15",
"occupation": "Software Engineer"
}
}
}
Ejemplo con varias matrices de riesgo
{
"type": "person",
"name": "María González",
"taxId": "20-12345678-9",
"countryCode": "AR",
"riskMatrixIds": [
"550e8400-e29b-41d4-a716-446655440000",
"660e8400-e29b-41d4-a716-446655440001"
],
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15"
}
}
}
Combinado con enriquecimientos y monitoreo Gu1
Matriz de riesgo + enrichments locales + sanciones Gu1 en lista vigilada (mismo patrón que Crear entidad):{
"type": "person",
"name": "María González",
"taxId": "20-12345678-9",
"countryCode": "AR",
"riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_renaper_data_enrichment",
"ar_repet_person_enrichment",
"global_gueno_sanctions_enrichment"
]
},
"monitoring": {
"main": {
"global_gueno_sanctions_enrichment": {
"watchlist": true
}
}
},
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15"
}
}
}
- Se crea la persona
- Corren los enrichments listados (RENAPER, REPET, Gu1 sanciones)
- Gu1 sanciones usa op 1 (lista vigilada) solo si
monitoringy Marketplace lo permiten - La matriz de riesgo evalúa con los datos recopilados
- Alertas y puntaje según reglas
Respuesta
boolean
Indica si la persona fue creada exitosamente
object
El objeto de persona creado incluyendo:
id- ID interno de gu1externalId- Tu ID externoorganizationId- Tu ID de organizacióntype- Siempre “person”name- Nombre de la personariskScore- Puntuación de riesgo inicial (0-100)status- Estado de la personaentityData- Datos específicos de la personaattributes- Atributos personalizadoscreatedAt- Marca de tiempo de creaciónupdatedAt- Marca de tiempo de última actualización
object
Resultado de la ejecución de reglas (solo presente cuando se ejecutaron reglas, p. ej. cuando skipRulesExecution es
false y hay matriz de riesgo configurada), incluyendo:- success (boolean) - Si las reglas se ejecutaron correctamente
- rulesTriggered (number) - Número de reglas disparadas
- alerts (array) - Alertas generadas por las reglas
- riskScore (number) - Puntuación de riesgo final
- decision (string) - Decisión final (APPROVE, REJECT, HOLD, REVIEW_REQUIRED)
- rulesExecutionSummary (object) - Presente cuando se ejecutaron reglas. Ver abajo la estructura.
object
En la raíz de la respuesta (igual que la API de transacciones). Mismo valor que
rulesResult.rulesExecutionSummary. Solo presente cuando se ejecutaron reglas (p. ej. skipRulesExecution es false). Resumen de qué reglas hicieron match (hit) vs no (no hit), acciones ejecutadas y puntuación total. Omitido cuando las reglas no se ejecutaron.- rulesHit (array) - Reglas cuyas condiciones se cumplieron. Cada ítem: name, description, score, priority, category, status (p. ej.
active,shadow), conditions (array de{ field, value, operator? }), actions (alerts, suggestion, status, assignedUser). - rulesNoHit (array) - Reglas evaluadas pero cuyas condiciones no se cumplieron. Misma estructura que rulesHit (incluye acciones configuradas, no ejecutadas).
- actionsExecuted (object) - Acciones ejecutadas agregadas de todas las reglas que hicieron hit: alerts, suggestion (
BLOCK|SUSPEND|FLAG, mayor peso), status (estado aplicado a la entidad, si hay), assignedUser ({ userId }, si hay), customKeys (array de strings, opcional) — claves de acciones personalizadas de las reglas que hicieron match; para integraciones/workflows. - totalScore (number) - Suma del score de todas las reglas que hicieron hit y no están en estado
shadow.
Ejemplo de Solicitud
curl -X POST http://api.gu1.ai/entities \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "person",
"externalId": "customer_12345",
"name": "María González",
"countryCode": "AR",
"taxId": "20-12345678-9",
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15",
"nationality": "AR",
"occupation": "Software Engineer",
"income": 85000,
"incomeCurrency": "USD",
"email": "maria.gonzalez@example.com",
"phone": "+54 11 1234-5678",
"address": "Av. Corrientes 1234",
"city": "Buenos Aires",
"state": "CABA",
"country": "Argentina",
"postalCode": "C1043"
}
},
"attributes": {
"customerSince": "2024-01-15",
"accountType": "premium"
}
}'
const response = await fetch('http://api.gu1.ai/entities', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
type: 'person',
externalId: 'customer_12345',
name: 'María González',
countryCode: 'AR',
taxId: '20-12345678-9',
entityData: {
person: {
firstName: 'María',
lastName: 'González',
dateOfBirth: '1985-03-15',
nationality: 'AR',
occupation: 'Software Engineer',
income: 85000,
incomeCurrency: 'USD',
email: 'maria.gonzalez@example.com',
phone: '+54 11 1234-5678',
address: 'Av. Corrientes 1234',
city: 'Buenos Aires',
state: 'CABA',
country: 'Argentina',
postalCode: 'C1043'
}
},
attributes: {
customerSince: '2024-01-15',
accountType: 'premium'
}
})
});
const data = await response.json();
console.log(data.entity);
import requests
response = requests.post(
'http://api.gu1.ai/entities',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'type': 'person',
'externalId': 'customer_12345',
'name': 'María González',
'countryCode': 'AR',
'taxId': '20-12345678-9',
'entityData': {
'person': {
'firstName': 'María',
'lastName': 'González',
'dateOfBirth': '1985-03-15',
'nationality': 'AR',
'occupation': 'Software Engineer',
'income': 85000,
'incomeCurrency': 'USD',
'email': 'maria.gonzalez@example.com',
'phone': '+54 11 1234-5678',
'address': 'Av. Corrientes 1234',
'city': 'Buenos Aires',
'state': 'CABA',
'country': 'Argentina',
'postalCode': 'C1043'
}
},
'attributes': {
'customerSince': '2024-01-15',
'accountType': 'premium'
}
}
)
entity = response.json()['entity']
print(entity)
Ejemplo de Respuesta
{
"success": true,
"entity": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "customer_12345",
"organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
"type": "person",
"name": "María González",
"taxId": "20-12345678-9",
"countryCode": "AR",
"riskScore": 25,
"status": "active",
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15",
"nationality": "AR",
"occupation": "Software Engineer",
"income": 85000,
"incomeCurrency": "USD",
"email": "maria.gonzalez@example.com",
"phone": "+54 11 1234-5678",
"address": "Av. Corrientes 1234",
"city": "Buenos Aires",
"state": "CABA",
"country": "Argentina",
"postalCode": "C1043"
}
},
"attributes": {
"customerSince": "2024-01-15",
"accountType": "premium"
},
"createdAt": "2024-10-03T14:30:00.000Z",
"updatedAt": "2024-10-03T14:30:00.000Z"
}
}
Respuestas de Error
400 Bad Request - Tax ID Inválido
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid CUIT format. Please check the format and try again.",
"details": {
"field": "taxId",
"taxIdName": "CUIT",
"providedValue": "20-12345678-9"
}
},
"entity": null
}
400 Bad Request - Faltan Campos Requeridos
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Missing required fields for person creation",
"details": {
"missingFields": ["firstName", "lastName"],
"requiredFields": ["firstName", "lastName", "dateOfBirth"],
"countryCode": "AR"
}
},
"entity": null
}
409 Conflict - Entidad Duplicada
{
"success": false,
"error": {
"code": "DUPLICATE_ENTITY",
"message": "Entity with this external_id already exists",
"details": {
"field": "external_id",
"value": "customer_12345",
"constraint": "entities_organization_external_id_unique"
}
},
"entity": null
}
401 Unauthorized
{
"error": "Invalid or missing API key",
"code": "INVALID_KEY"
}
Próximos Pasos
Después de crear una persona, puedes:- Obtener Detalles de Persona - Recuperar información completa de la persona
- Listar Personas - Consultar tus personas
- Actualizar Persona - Modificar datos de la persona
- Crear Validación KYC - Iniciar proceso de verificación KYC
Was this page helpful?