> ## 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.

# Obtener una persona por ID

> Recuperar información detallada sobre una persona — para entidades de persona en la plataforma KYC y análisis de riesgo gu1, con ejemplos para get.

## Resumen

Recupera los detalles completos de una persona, incluyendo el estado de evaluación y la valoración de riesgo. Podés consultar una persona de tres formas:

| Método              | Endpoint                                    | Cuándo usar                                                            |
| ------------------- | ------------------------------------------- | ---------------------------------------------------------------------- |
| **Por ID**          | `GET /entities/{id}`                        | Tenés el UUID interno de la entidad en gu1                             |
| **Por external ID** | `GET /entities/by-external-id/{externalId}` | Usás tu propio identificador (ej. `customer_12345`)                    |
| **Por tax ID**      | `GET /entities/by-tax-id/{taxId}`           | Tenés el documento fiscal (CUIT, CPF, etc.) y querés buscar la persona |

Los tres devuelven el mismo objeto. El alcance de organización se aplica según tu API key.

## Endpoints

### Obtener por ID

```
GET http://api.gu1.ai/entities/{id}
```

<ParamField path="id" type="string" required>
  ID único (UUID) de gu1 de la persona a recuperar
</ParamField>

### Obtener por external ID

```
GET http://api.gu1.ai/entities/by-external-id/{externalId}
```

<ParamField path="externalId" type="string" required>
  Tu identificador externo de esta persona (el valor enviado al crear la entidad)
</ParamField>

### Obtener por tax ID

```
GET http://api.gu1.ai/entities/by-tax-id/{taxId}
```

<ParamField path="taxId" type="string" required>
  Número de identificación fiscal (formato según país: CUIT Argentina, CPF Brasil, etc.). Debe coincidir con el tax ID almacenado de la entidad en tu organización.
</ParamField>

## Autenticación

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

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

## Respuesta

Devuelve el objeto completo de la persona con los siguientes campos:

<ResponseField name="id" type="string">
  ID interno de entidad de gu1
</ResponseField>

<ResponseField name="externalId" type="string">
  Tu identificador externo para esta persona
</ResponseField>

<ResponseField name="organizationId" type="string">
  Tu ID de organización
</ResponseField>

<ResponseField name="type" type="string">
  Siempre "person"
</ResponseField>

<ResponseField name="name" type="string">
  Nombre para mostrar de la persona
</ResponseField>

<ResponseField name="taxId" type="string">
  Número de identificación fiscal
</ResponseField>

<ResponseField name="countryCode" type="string">
  Código de país ISO 3166-1 alpha-2
</ResponseField>

<ResponseField name="riskScore" type="number">
  Puntuación de riesgo calculada de 0 (bajo riesgo) a 100 (alto riesgo)
</ResponseField>

<ResponseField name="riskFactors" type="array">
  Array de factores de riesgo identificados que contribuyen a la puntuación de riesgo
</ResponseField>

<ResponseField name="status" type="string">
  Estado de la persona: `active`, `inactive`, `under_review`, `approved`, `rejected`, `suspended`
</ResponseField>

<ResponseField name="kycVerified" type="boolean">
  Si la verificación KYC ha sido completada
</ResponseField>

<ResponseField name="kycProvider" type="string">
  Nombre del proveedor KYC utilizado (si aplica)
</ResponseField>

<ResponseField name="kycData" type="object">
  Datos de verificación KYC del proveedor
</ResponseField>

<ResponseField name="entityData" type="object">
  Estructura de datos específica de la persona
</ResponseField>

<ResponseField name="attributes" type="object">
  Atributos personalizados como pares clave-valor
</ResponseField>

<ResponseField name="currentEvaluation" type="object">
  Resultados de evaluación de IA más recientes (null si no existe evaluación)

  * `id` - ID de evaluación
  * `entityId` - ID de entidad
  * `evaluationType` - Tipo de evaluación realizada
  * `result` - Resultado de evaluación
  * `confidence` - Puntuación de confianza (0-1)
  * `evaluatedAt` - Marca de tiempo de evaluación
</ResponseField>

<ResponseField name="createdAt" type="string">
  Marca de tiempo ISO 8601 de creación de la persona
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Marca de tiempo ISO 8601 de última actualización
</ResponseField>

<ResponseField name="deletedAt" type="string">
  Marca de tiempo ISO 8601 de eliminación lógica (null si no está eliminada)
</ResponseField>

## Ejemplos

### Por ID (UUID)

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
  const person = await response.json();
  ```

  ```python Python theme={null}
  import requests
  response = requests.get(
      'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )
  person = response.json()
  print(person)
  ```
</CodeGroup>

### Por external ID

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/entities/by-external-id/customer_12345" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const externalId = 'customer_12345';
  const response = await fetch(
    `http://api.gu1.ai/entities/by-external-id/${encodeURIComponent(externalId)}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
  const person = await response.json();
  ```

  ```python Python theme={null}
  import requests
  response = requests.get(
      "http://api.gu1.ai/entities/by-external-id/customer_12345",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  person = response.json()
  ```
</CodeGroup>

### Por tax ID

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/entities/by-tax-id/20-12345678-9" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const taxId = '20-12345678-9';
  const response = await fetch(
    `http://api.gu1.ai/entities/by-tax-id/${encodeURIComponent(taxId)}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
  const person = await response.json();
  ```

  ```python Python theme={null}
  import requests
  response = requests.get(
      "http://api.gu1.ai/entities/by-tax-id/20-12345678-9",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  person = response.json()
  ```
</CodeGroup>

### Ejemplo de Respuesta

```json theme={null}
{
  "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,
  "riskFactors": [
    {
      "factor": "new_customer",
      "impact": 15,
      "description": "Customer registered within last 30 days"
    },
    {
      "factor": "high_income_occupation",
      "impact": -10,
      "description": "Professional occupation with verified income"
    }
  ],
  "status": "active",
  "kycVerified": true,
  "kycProvider": "gueno_ai",
  "kycData": {
    "verificationDate": "2024-10-03T14:30:00Z",
    "documentsVerified": ["national_id", "proof_of_address"],
    "livenessCheck": "passed",
    "overallStatus": "approved"
  },
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15",
      "nationality": "AR",
      "occupation": "Software Engineer",
      "income": 85000
    }
  },
  "attributes": {
    "email": "maria.gonzalez@example.com",
    "phone": "+54 11 1234-5678",
    "customerSince": "2024-01-15",
    "accountTier": "premium"
  },
  "currentEvaluation": {
    "id": "eval_abc123",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "evaluationType": "risk_assessment",
    "result": {
      "overallRisk": "low",
      "amlRisk": "low",
      "fraudRisk": "low",
      "complianceScore": 95,
      "recommendation": "approve"
    },
    "confidence": 0.92,
    "evaluatedAt": "2024-10-03T14:35:00Z"
  },
  "createdAt": "2024-10-03T14:30:00.000Z",
  "updatedAt": "2024-10-03T14:35:00.000Z",
  "deletedAt": null
}
```

## Respuestas de Error

### 404 Not Found

```json theme={null}
{
  "error": "Entity not found"
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": "Invalid or missing API key"
}
```

### 500 Internal Server Error

```json theme={null}
{
  "error": "Failed to fetch entity"
}
```

## Casos de Uso

### Verificación de KYC

Recuperar un cliente para verificar su estado KYC antes de aprobar una transacción:

```javascript theme={null}
const person = await fetch(`http://api.gu1.ai/entities/${customerId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(res => res.json());

if (person.kycVerified && person.status === 'active') {
  // Proceder con la transacción
  console.log('Customer verified, risk score:', person.riskScore);
} else {
  // Solicitar verificación adicional
  console.log('KYC verification required');
}
```

### Monitoreo de Puntuación de Riesgo

Verificar la puntuación de riesgo actual y factores para monitoreo continuo:

```python theme={null}
person = requests.get(
    f'http://api.gu1.ai/entities/{person_id}',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
).json()

if person['riskScore'] > 70:
    # Alto riesgo - activar debida diligencia mejorada
    print(f"High risk person detected: {person['riskScore']}")
    print("Risk factors:", person['riskFactors'])
elif person['riskScore'] > 40:
    # Riesgo medio - aplicar monitoreo adicional
    print(f"Medium risk person: {person['riskScore']}")
```

## Próximos Pasos

* [Actualizar Persona](/es/api-reference/person/update) - Modificar atributos de persona
* [Listar Personas](/es/api-reference/person/list) - Consultar múltiples personas
* [Crear Validación KYC](/es/use-cases/kyc/create-validation) - Iniciar verificación de identidad