> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
## 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:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Cuerpo de la Solicitud
Debe ser `person` para crear una entidad de persona
Tu identificador único para esta persona en tu sistema
Nombre para mostrar de la persona
Código de país ISO 3166-1 alpha-2 (ej., "US", "BR", "AR")
Número de identificación fiscal (validado según el país)
📋 Ver [Formatos de Tax ID por País](/es/api-reference/entities/tax-id-formats) para formatos aceptados y reglas de validación para cada país.
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](/es/api-reference/entities/create): `timezone` + `weekly` (`monday`…`sunday`, `start`/`end` o `closed`). Valores de `timezone`: [Enum zona horaria](/es/api-reference/transactions/time-zone-enum).
**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)
**Opcional** - Estructura de datos específica de persona (ver más abajo)
**¿Cuándo usar entityData?**
* **Opcional para creación básica de entidad** - Puedes crear una persona con solo `type`, `name`, `taxId` y `countryCode`
* **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
**Ejemplo Mínimo:**
```json theme={null}
{
"type": "person",
"name": "Juan Pérez",
"taxId": "12345678",
"countryCode": "ES"
// No se necesita entityData para creación básica
}
```
**Ejemplo Completo (con datos KYC):**
```json theme={null}
{
"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"
}
}
}
```
Fecha de registro de la persona en formato ISO 8601 datetime (ej., "2024-01-15T10:30:00Z")
Marca esta persona como cliente para fines de seguimiento
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](#ejecución-de-matriz-de-riesgo) abajo.
Forma preferida para **varias** matrices: lista ordenada de UUIDs de tu organización. Si viene informada y no vacía, tiene precedencia sobre `riskMatrixId`.
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.
Estado inicial de la persona. Opciones:
* `active` - Persona activa
* `inactive` - Persona inactiva
* `blocked` - Persona bloqueada
* `under_review` - Persona en revisión (predeterminado)
* `suspended` - Persona suspendida
* `expired` - Registro de persona expirado
* `deleted` - Eliminación lógica
* `rejected` - Persona rechazada
Configurar la ejecución automática de enriquecimientos al crear la persona.
**Estructura:**
```json theme={null}
{
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_renaper_data_enrichment",
"ar_repet_person_enrichment",
"global_gueno_sanctions_enrichment"
],
"excludeEnrichments": []
}
```
**Propiedades:**
* `executeAllActiveEnrichments` (boolean) - Ejecutar todos los enriquecimientos activos de la organización
* `enrichments` (string\[]) - Códigos de enriquecimiento a ejecutar tras crear la entidad
* `enrichmentGroupRefs` (string\[], opcional) - Slugs de grupos del Marketplace
* `excludeEnrichments` (string\[], opcional) - Códigos a omitir del conjunto final
Los códigos `*_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](/es/api-reference/integrations/person-provider-codes) y [Crear entidad](/es/api-reference/entities/create).
Opcional. Solo afecta enriquecimientos que admiten **monitoreo continuo** (hoy: **`global_gueno_sanctions_enrichment`**). Misma semántica que [Crear entidad — monitoreo](/es/api-reference/entities/create#ejemplo-monitoreo-de-sanciones-gu1-al-crear): `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)
```json theme={null}
{
"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 objeto `entityData.person` debe contener:
```json theme={null}
{
"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):
```json theme={null}
{
"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 proporcionando `riskMatrixId` o `riskMatrixIds`.
### Cómo funciona
1. **Obtenga su(s) ID(s) de Matriz de Riesgo** desde el panel de gu1 (formato: UUID)
2. **Incluya `riskMatrixId` o `riskMatrixIds` en su solicitud de creación**
3. 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
```json theme={null}
{
"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
```json theme={null}
{
"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](/es/api-reference/entities/create#ejemplo-monitoreo-de-sanciones-gu1-al-crear)):
```json theme={null}
{
"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"
}
}
}
```
**Flujo:**
1. Se crea la persona
2. Corren los enrichments listados (RENAPER, REPET, Gu1 sanciones)
3. Gu1 sanciones usa **op 1** (lista vigilada) solo si `monitoring` y Marketplace lo permiten
4. La matriz de riesgo evalúa con los datos recopilados
5. Alertas y puntaje según reglas
***
## Respuesta
Indica si la persona fue creada exitosamente
El objeto de persona creado incluyendo:
* `id` - ID interno de gu1
* `externalId` - Tu ID externo
* `organizationId` - Tu ID de organización
* `type` - Siempre "person"
* `name` - Nombre de la persona
* `riskScore` - Puntuación de riesgo inicial (0-100)
* `status` - Estado de la persona
* `entityData` - Datos específicos de la persona
* `attributes` - Atributos personalizados
* `createdAt` - Marca de tiempo de creación
* `updatedAt` - Marca de tiempo de última actualización
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.
**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
```bash cURL theme={null}
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"
}
}'
```
```javascript JavaScript theme={null}
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);
```
```python Python theme={null}
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
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"error": "Invalid or missing API key",
"code": "INVALID_KEY"
}
```
## Próximos Pasos
Después de crear una persona, puedes:
1. [Obtener Detalles de Persona](/es/api-reference/person/get) - Recuperar información completa de la persona
2. [Listar Personas](/es/api-reference/person/list) - Consultar tus personas
3. [Actualizar Persona](/es/api-reference/person/update) - Modificar datos de la persona
4. [Crear Validación KYC](/es/use-cases/kyc/create-validation) - Iniciar proceso de verificación KYC