> ## 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 entidad por ID

> Recuperar información detallada sobre una persona o empresa — en el modelo universal de entidades gu1 para KYC, KYB y análisis de riesgo.

## Descripción General

Recupera los detalles completos de una entidad específica por ID, incluyendo su estado de evaluación actual y evaluación de riesgo.

## Endpoint

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

## Autenticación

Requiere una clave API válida en el encabezado de autorización:

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

## Parámetros de Ruta

<ParamField path="id" type="string" required>
  El ID único de gu1 de la entidad a recuperar
</ParamField>

## Respuesta

Devuelve el objeto de entidad completo con los siguientes campos:

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

<ResponseField name="externalId" type="string">
  Su identificador externo para esta entidad
</ResponseField>

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

<ResponseField name="type" type="string">
  Tipo de entidad (person o company)
</ResponseField>

<ResponseField name="name" type="string">
  Nombre de visualización de la entidad
</ResponseField>

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

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

<ResponseField name="nationality" type="string | null">
  Nacionalidad en raíz (ISO 3166-1 alfa-2, denormalizada; puede ser `null` en registros antiguos). Complementa `entityData.person.nationality` / `entityData.company.nationality`.
</ResponseField>

<ResponseField name="riskScore" type="number">
  Puntuación de riesgo calculada de 0 (riesgo bajo) a 100 (riesgo alto)
</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 entidad: `active`, `inactive`, `under_review`, `approved`, `rejected`, `suspended`
</ResponseField>

<ResponseField name="kycVerified" type="boolean">
  Si se ha completado la verificación KYC
</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 de entidad específica del tipo
</ResponseField>

<ResponseField name="attributes" type="object">
  Atributos personalizados, almacenados **tal cual**. Los valores escalares/array quedan en la raíz (sin categoría); un objeto anidado agrupa sus claves internas bajo esa categoría (p. ej. `{ "contact": { "phone": "..." } }`). La respuesta devuelve la misma forma que se escribió — el input anidado **no** se aplana. Reglas y webhooks leen la forma almacenada (`attributes.phone` o `attributes.contact.phone`).
</ResponseField>

<ResponseField name="currentEvaluation" type="object">
  Últimos resultados de evaluación de IA (null si no existe evaluación)

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

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

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

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

## Ejemplos

### Obtener Entidad de Persona

<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 entity = await response.json();
  console.log(entity);
  ```

  ```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'
      }
  )

  entity = response.json()
  print(entity)
  ```
</CodeGroup>

### Ejemplo de Respuesta - Entidad de Persona

```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",
  "nationality": "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
}
```

### Ejemplo de Respuesta - Entidad de Empresa

```json theme={null}
{
  "id": "660e9511-f39c-52e5-b827-557766551111",
  "externalId": "company_789",
  "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "12.345.678/0001-90",
  "countryCode": "BR",
  "nationality": "BR",
  "riskScore": 35,
  "riskFactors": [
    {
      "factor": "new_business",
      "impact": 20,
      "description": "Company incorporated less than 2 years ago"
    },
    {
      "factor": "high_growth_industry",
      "impact": 15,
      "description": "Operating in high-growth tech sector"
    }
  ],
  "status": "active",
  "kycVerified": true,
  "kycProvider": "gueno_ai",
  "kycData": {
    "verificationDate": "2024-10-03T15:00:00Z",
    "documentsVerified": ["articles_of_incorporation", "tax_registration", "beneficial_owners"],
    "overallStatus": "approved"
  },
  "entityData": {
    "company": {
      "legalName": "Tech Solutions Sociedade Anônima",
      "tradeName": "Tech Solutions",
      "incorporationDate": "2020-06-15",
      "industry": "Software Development",
      "employeeCount": 50,
      "revenue": 5000000
    }
  },
  "attributes": {
    "website": "https://techsolutions.com.br",
    "registeredAddress": "Av. Paulista, 1000, São Paulo",
    "partnershipTier": "gold",
    "monthlyVolume": 250000
  },
  "currentEvaluation": {
    "id": "eval_xyz789",
    "entityId": "660e9511-f39c-52e5-b827-557766551111",
    "evaluationType": "kyb_assessment",
    "result": {
      "overallRisk": "medium",
      "financialRisk": "low",
      "reputationalRisk": "low",
      "complianceScore": 88,
      "recommendation": "approve_with_monitoring"
    },
    "confidence": 0.87,
    "evaluatedAt": "2024-10-03T15:05:00Z"
  },
  "createdAt": "2024-10-03T15:00:00.000Z",
  "updatedAt": "2024-10-03T15:05:00.000Z",
  "deletedAt": null
}
```

### Ejemplo de Respuesta - Entidad de Transacción

```json theme={null}
{
  "id": "770f0622-g40d-63f6-c938-668877662222",
  "externalId": "txn_98765",
  "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
  "type": "transaction",
  "name": "Wire Transfer - $50,000",
  "taxId": null,
  "countryCode": "US",
  "nationality": null,
  "riskScore": 45,
  "riskFactors": [
    {
      "factor": "high_value_transaction",
      "impact": 30,
      "description": "Transaction amount exceeds $10,000 threshold"
    },
    {
      "factor": "wire_transfer",
      "impact": 15,
      "description": "Wire transfers carry higher fraud risk"
    }
  ],
  "status": "under_review",
  "kycVerified": false,
  "kycProvider": null,
  "kycData": null,
  "entityData": {
    "transaction": {
      "transactionId": "txn_98765",
      "type": "wire_transfer",
      "status": "completed",
      "amount": 50000,
      "currency": "USD",
      "paymentMethod": "bank_transfer",
      "originEntityId": "customer_12345",
      "destinationEntityId": "merchant_456",
      "transactedAt": "2024-10-03T14:30:00Z",
      "riskScore": 45,
      "flagged": true,
      "category": "business_payment",
      "description": "Payment for professional services"
    }
  },
  "attributes": {
    "ipAddress": "192.168.1.100",
    "deviceId": "device_abc123",
    "userAgent": "Mozilla/5.0...",
    "referenceNumber": "REF-2024-10-03-001"
  },
  "currentEvaluation": {
    "id": "eval_def456",
    "entityId": "770f0622-g40d-63f6-c938-668877662222",
    "evaluationType": "fraud_detection",
    "result": {
      "overallRisk": "medium",
      "fraudProbability": 0.35,
      "amlFlags": ["high_value", "cross_border"],
      "recommendation": "manual_review"
    },
    "confidence": 0.78,
    "evaluatedAt": "2024-10-03T14:32:00Z"
  },
  "createdAt": "2024-10-03T14:30:00.000Z",
  "updatedAt": "2024-10-03T14:32:00.000Z",
  "deletedAt": null
}
```

## Respuestas de Error

### 404 No Encontrado

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

### 401 No Autorizado

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

### 500 Error Interno del Servidor

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

## Casos de Uso

### Verificación de Estado KYC

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

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

if (entity.kycVerified && entity.status === 'active') {
  // Proceder con la transacción
  console.log('Cliente verificado, puntuación de riesgo:', entity.riskScore);
} else {
  // Solicitar verificación adicional
  console.log('Se requiere verificación KYC');
}
```

### Monitoreo de Puntuación de Riesgo

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

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

if entity['riskScore'] > 70:
    # Alto riesgo - activar debida diligencia mejorada
    print(f"Entidad de alto riesgo detectada: {entity['riskScore']}")
    print("Factores de riesgo:", entity['riskFactors'])
elif entity['riskScore'] > 40:
    # Riesgo medio - aplicar monitoreo adicional
    print(f"Entidad de riesgo medio: {entity['riskScore']}")
```

### Análisis de Resultados de Evaluación

Acceder a la última evaluación de IA para comprender los detalles de la evaluación:

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

if (entity.currentEvaluation) {
  console.log('Confianza de la evaluación:', entity.currentEvaluation.confidence);
  console.log('Recomendación:', entity.currentEvaluation.result.recommendation);
  console.log('Evaluación de riesgo:', entity.currentEvaluation.result.overallRisk);
}
```

## Próximos Pasos

* [Actualizar Entidad](/api-reference/entities/update) - Modificar atributos de entidad
* [Listar Entidades](/api-reference/entities/list) - Consultar múltiples entidades
* [Solicitar Análisis de IA](/en/api-reference/entities/analyze) - Obtener evaluación de riesgo
* [Ver Línea de Tiempo de Entidad](/en/api-reference/events/list-by-entity) - Ver historial de entidad