> ## 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 persona automáticamente con enriquecimiento

> Crear automáticamente persona con datos enriquecidos de registros — para entidades de persona en la plataforma KYC y análisis de riesgo gu1.

## Resumen

El endpoint de creación automática de persona te permite crear personas proporcionando información mínima (ID fiscal y país). El sistema automáticamente:

* Obtiene datos de la persona de registros oficiales
* Enriquece la persona con información adicional
* Ejecuta enriquecimientos automáticamente

Esto es ideal para procesos KYC (Conoce a tu Cliente) donde deseas incorporar clientes con información completa automáticamente.

## Endpoint

```
POST http://api.gu1.ai/entities/automatic
```

## Autenticación

Requiere una clave API válida en el encabezado Authorization:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Cuerpo de la Solicitud

<ParamField body="taxId" type="string" required>
  Número de identificación fiscal de la persona (ej., CPF para Brasil, CURP para México, CUIT para Argentina)

  <Tip>
    📋 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.
  </Tip>
</ParamField>

<ParamField body="country" type="string" required>
  Código de país ISO 3166-1 alpha-2 (ej., "BR", "MX", "AR", "CL")
</ParamField>

<ParamField body="type" type="string" required>
  Debe establecerse en `person`
</ParamField>

<ParamField body="externalId" type="string">
  Tu identificador único para esta persona (opcional, se generará automáticamente si no se proporciona)
</ParamField>

<ParamField body="isClient" type="boolean" default="false">
  Marca esta persona como cliente para fines de seguimiento
</ParamField>

<ParamField body="riskMatrixId" type="string | string[]">
  Uno o más UUIDs de matrices de riesgo (legacy: un solo UUID). Tras la creación se ejecutan reglas activas de esas matrices (salvo `skipRulesExecution: true`).
</ParamField>

<ParamField body="riskMatrixIds" type="string[]">
  Preferido para **varias** matrices: lista ordenada de UUIDs. Tiene precedencia sobre `riskMatrixId` cuando viene informada y no vacía.
</ParamField>

<ParamField body="skipRulesExecution" type="boolean" default="false">
  Omitir la ejecución automática de reglas después de crear la persona
</ParamField>

<ParamField body="status" type="string" default="under_review">
  Estado inicial de la persona
</ParamField>

<ParamField body="operationalHours" type="object | null">
  Horario operativo opcional de la **entidad principal** (`timezone` + `weekly`). Se persiste en creación automática igual que en creación manual de entidades. No se aplica a accionistas/relaciones creadas por `depth`.
</ParamField>

<ParamField body="depth" type="number" default="0">
  Profundidad de extracción de relaciones (0-5). Controla cuántos niveles de relaciones se obtienen y crean automáticamente.

  * `0`: Sin relaciones (solo entidad principal)
  * `1`: Solo relaciones directas
  * `2`: Relaciones + sus relaciones
  * `3-5`: Niveles adicionales (usar con precaución - puede crear muchas entidades)
</ParamField>

<ParamField body="autoExecuteIntegrations" type="object">
  Configurar la ejecución automática de integraciones para la entidad de persona principal. Ver [Referencia de Códigos de Proveedor](/es/api-reference/integrations/provider-codes) para códigos disponibles.

  **Tipo**: `object` (opcional)

  **Propiedades:**

  * `executeAllActiveEnrichments` (boolean, opcional, predeterminado: `false`) - Ejecutar todas las integraciones de enriquecimiento activas
  * `enrichments` (array, opcional, predeterminado: `[]`) - Array de códigos específicos de proveedor de enriquecimiento a ejecutar
  * `enrichmentGroupRefs` (array de strings, opcional) - Slugs de **grupos de enriquecimiento** del Marketplace (solo enriquecimientos). Con `executeAllActiveEnrichments: false`, se resuelven los grupos y se fusionan con `enrichments` explícitos. Con `executeAllActiveEnrichments: true`, los refs de grupo no se usan; los `enrichments` explícitos pueden seguir añadiendo códigos tras el conjunto activo.

  ```typescript theme={null}
  {
    executeAllActiveEnrichments?: boolean; // predeterminado: false
    enrichments?: ValidProviderCodesEnum[]; // predeterminado: []
    enrichmentGroupRefs?: string[];
  }
  ```

  **Ejemplo:**

  ```json theme={null}
  {
    "executeAllActiveEnrichments": false,
    "enrichments": ["br_bdc_basic_data_enrichment"],
    "enrichmentGroupRefs": ["my_marketplace_group_slug"],
  }
  ```
</ParamField>

<ParamField body="autoExecuteIntegrationsShareholders" type="object">
  Configurar la ejecución automática de integraciones para relaciones descubiertas. Útil al usar `depth > 0`. Ver [Referencia de Códigos de Proveedor](/es/api-reference/integrations/provider-codes) para códigos disponibles.

  **Tipo**: `object` (opcional)

  **Propiedades:**

  * `executeAllActiveEnrichments` (boolean, opcional, predeterminado: `false`) - Ejecutar todos los enriquecimientos activos en entidades relacionadas
  * `enrichments` (object, opcional) - Enriquecimientos específicos por tipo de entidad
    * `company` (array, predeterminado: `[]`) - Enriquecimientos para relaciones de empresa
    * `person` (array, predeterminado: `[]`) - Enriquecimientos para relaciones de persona
  * `enrichmentGroupRefs` (array de strings, opcional) - Mismos slugs que en el objeto principal; con `executeAllActiveEnrichments: false` se aplican **tanto a `company` como a `person`**. Con `executeAllActiveEnrichments: true` en este objeto, los refs de grupo no se usan; los `enrichments` explícitos por tipo pueden seguir añadiendo códigos tras el activo de cada lado.

  ```typescript theme={null}
  {
    executeAllActiveEnrichments?: boolean;
    enrichments?: {
      company?: ValidProviderCodesEnum[];
      person?: ValidProviderCodesEnum[];
    };
    enrichmentGroupRefs?: string[];
  }
  ```

  **Ejemplo:**

  ```json theme={null}
  {
    "enrichments": {
      "person": ["br_cpfcnpj_complete_person_enrichment"],
      "company": ["br_cpfcnpj_complete_company_enrichment"]
    },
    "enrichmentGroupRefs": ["related_entities_group_slug"]
  }
  ```
</ParamField>

## Códigos de Enrichment Obligatorios por País

<Warning>
  Al usar códigos de enrichment específicos (no `executeAllActiveEnrichments: true`), ciertos enrichments son **obligatorios** para que la creación automática funcione. Sin ellos, el sistema no puede obtener los datos básicos de la persona de los registros oficiales y la solicitud fallará.
</Warning>

### Brasil (BR)

| Escenario                      | Código(s) de Enrichment Obligatorio(s)                                          | Descripción                                                                                                            |
| ------------------------------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Entidad principal**          | `br_bdc_basic_data_enrichment`                                                  | Obtiene datos de la persona vía BDC/CPF (nombre completo, fecha de nacimiento, dirección, etc.)                        |
| **Relacionados** (`depth > 0`) | `br_bdc_related_companies_enrichment` **Y** `br_bdc_related_persons_enrichment` | Ambos obligatorios en `autoExecuteIntegrations.enrichments`. Obtiene empresas y personas relacionadas con el individuo |

<Info>
  Los enrichments de relaciones deben incluirse en el array `autoExecuteIntegrations.enrichments` de la **entidad principal** (no en `autoExecuteIntegrationsShareholders`), porque el sistema necesita ejecutarlos sobre la persona principal para descubrir las relaciones. El campo `autoExecuteIntegrationsShareholders` controla qué enrichments ejecutar **sobre cada entidad relacionada** después de ser creada.
</Info>

### Argentina (AR)

| Escenario             | Código de Enrichment Obligatorio            | Descripción                          |
| --------------------- | ------------------------------------------- | ------------------------------------ |
| **Entidad principal** | `ar_nosis_extended_verification_enrichment` | Obtiene datos de la persona de Nosis |

<Warning>
  Argentina **no soporta** la creación automática de relaciones aún. El parámetro `depth` debe ser `0`.
</Warning>

<ParamField body="customData" type="object">
  **Opcional** — Datos del cliente para la **persona principal** que no deben ser reemplazados por enrichments. Detalle completo (tabla root vs `entityData`): [Creación automática de entidades](/es/api-reference/entities/create-automatic).

  Campos: `name`, `email`, `phone`, `birthDate` → `entityData.person.dateOfBirth`, `address` → `entityData.person.address`, `gender` (enum: `M` | `F` | `male` | `female` | `other` | `unknown` — usar `other` para no binario; ver [Crear entidad](/es/api-reference/entities/create#entidad-persona)).

  **Ejemplo:**

  ```json theme={null}
  {
    "taxId": "23450679909",
    "country": "AR",
    "type": "person",
    "customData": {
      "name": "LEDESMA BRUNO EZEQUIEL",
      "email": "cliente@empresa.com",
      "phone": "+541112345678",
      "birthDate": "1990-05-15",
      "address": "Av. Corrientes 1234, CABA"
    }
  }
  ```
</ParamField>

<ParamField body="attributes" type="object">
  **Opcional** - Atributos personalizados como pares clave-valor para la entidad creada.

  Se aplican solo a la entidad principal (la persona creada), no a relaciones/accionistas. Útil para segmentos de negocio, etiquetas, IDs internos o cualquier metadato que quieras asociar desde el momento de la creación.

  **Estructura:** objeto con claves string y valores de cualquier tipo (string, number, boolean, array, etc.).

  **Ejemplo:**

  ```json theme={null}
  {
    "businessSegments": ["retail", "fintech"],
    "source": "onboarding_web",
    "tags": ["vip", "high_volume"]
  }
  ```
</ParamField>

## Respuesta

<ResponseField name="success" type="boolean">
  Indica si la persona fue creada exitosamente
</ResponseField>

<ResponseField name="data" type="object">
  Información completa sobre la creación:

  * `entity` (object) - La persona creada con todos los datos
  * `summary` (object) - Resumen de creación
  * `errors` (object, opcional) - Detalles de cualquier error
</ResponseField>

<ResponseField name="rulesResult" type="object">
  Resultado de la ejecución de reglas (solo presente cuando se ejecutaron reglas, p. ej. cuando **skipRulesExecution** es `false` y hay matriz configurada vía `riskMatrixId` o `riskMatrixIds`), o null. Cuando está presente, incluye:

  * **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.
</ResponseField>

<ResponseField name="rulesExecutionSummary" type="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 y se ejecutó la matriz de riesgo).** Resumen de qué reglas hicieron match (hit) vs no (no hit), acciones ejecutadas y puntuación total. Omitido cuando las reglas no se ejecutaron. Estructura completa y ejemplo: [Resumen de Ejecución de Reglas](/es/api-reference/rules-execution-summary).

  * **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`.
</ResponseField>

## Ejemplos

### Crear Persona con Todas las Integraciones Activas

<CodeGroup>
  ```bash cURL theme={null}
  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,
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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'])
  ```
</CodeGroup>

### Crear Persona con Integraciones Específicas

<CodeGroup>
  ```bash cURL theme={null}
  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"]
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

## Ejemplo de Respuesta

```json theme={null}
{
  "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
}
```

## Respuestas de Error

### 400 Bad Request - Tax ID Inválido

```json theme={null}
{
  "success": false,
  "error": "Invalid CPF format for Brazil"
}
```

### 404 Not Found - Persona No Encontrada en Registro

```json theme={null}
{
  "success": false,
  "error": "Entity not found in official registry",
  "details": {
    "taxId": "123.456.789-00",
    "country": "BR",
    "registry": "Receita Federal"
  }
}
```

### 409 Conflict - Persona Ya Existe

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

## Mejores Prácticas

1. **Manejo de errores**: Siempre verifica el campo `success` en la respuesta
2. **Límite de tasa**: Ten en cuenta los límites de tasa al crear múltiples personas
3. **Selección de integración**: Elige integraciones específicas para un mejor control sobre costo y rendimiento

## Próximos Pasos

* [Obtener Persona](/es/api-reference/person/get) - Recuperar detalles de persona
* [Crear Persona Manualmente](/es/api-reference/person/create) - Crear personas con tus propios datos
* [Crear Validación KYC](/es/use-cases/kyc/create-validation) - Iniciar verificación de identidad