Skip to main content
GET
/
entities
/
{id}
Obtener
curl --request GET \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "<string>",
  "externalId": "<string>",
  "organizationId": "<string>",
  "type": "<string>",
  "name": "<string>",
  "taxId": "<string>",
  "countryCode": "<string>",
  "riskScore": 123,
  "riskFactors": [
    {}
  ],
  "status": "<string>",
  "kycVerified": true,
  "kycProvider": "<string>",
  "kycData": {},
  "entityData": {},
  "attributes": {},
  "currentEvaluation": {},
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>"
}

​
Descripción general

Recupera los detalles completos de una empresa, incluyendo el estado de evaluación y la valoración de riesgo. Podés consultar una empresa de tres formas:
MétodoEndpointCuándo usar
Por IDGET /entities/{id}Tenés el UUID interno de la entidad en gu1
Por external IDGET /entities/by-external-id/{externalId}Usás tu propio identificador (ej. business_456)
Por tax IDGET /entities/by-tax-id/{taxId}Tenés el CUIT/CNPJ y querés buscar la empresa
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}
​
id
string
required
ID único (UUID) de gu1 de la empresa a recuperar

​
Obtener por external ID

GET http://api.gu1.ai/entities/by-external-id/{externalId}
​
externalId
string
required
Tu identificador externo de esta empresa (el valor enviado al crear la entidad)

​
Obtener por tax ID

GET http://api.gu1.ai/entities/by-tax-id/{taxId}
​
taxId
string
required
Número de identificación fiscal (CUIT, CNPJ, etc.). Debe coincidir con el tax ID almacenado de la entidad en tu organización.

​
Autenticación

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

​
Respuesta

Devuelve el objeto completo de la empresa con los siguientes campos:
​
id
string
ID de entidad interno de gu1
​
externalId
string
Tu identificador externo para esta empresa
​
organizationId
string
ID de tu organización
​
type
string
Siempre “company”
​
name
string
Nombre para mostrar de la empresa
​
taxId
string
Número de identificación fiscal
​
countryCode
string
Código de país ISO 3166-1 alpha-2
​
riskScore
number
Puntuación de riesgo calculada de 0 (riesgo bajo) a 100 (riesgo alto)
​
riskFactors
array
Array de factores de riesgo identificados que contribuyen a la puntuación de riesgo
​
status
string
Estado de la empresa: active, inactive, under_review, approved, rejected, suspended
​
kycVerified
boolean
Si se completó la verificación KYB
​
kycProvider
string
Nombre del proveedor KYB utilizado (si aplica)
​
kycData
object
Datos de verificación KYB del proveedor
​
entityData
object
Estructura de datos específica de la empresa
​
attributes
object
Atributos personalizados como pares clave-valor
​
currentEvaluation
object
Resultados de la última evaluación AI (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
​
createdAt
string
Marca de tiempo ISO 8601 de creación de la empresa
​
updatedAt
string
Marca de tiempo ISO 8601 de última actualización
​
deletedAt
string
Marca de tiempo ISO 8601 de eliminación lógica (null si no está eliminada)

​
Ejemplos

​
Por ID (UUID)

curl -X GET http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Por external ID

curl -X GET "http://api.gu1.ai/entities/by-external-id/business_456" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Por tax ID

curl -X GET "http://api.gu1.ai/entities/by-tax-id/30-71234567-8" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Ejemplo de respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "business_12345",
  "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
  "type": "company",
  "name": "María González",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskScore": 25,
  "riskFactors": [
    {
      "factor": "new_business",
      "impact": 15,
      "description": "Business 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": {
    "company": {
      "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",
    "businessSince": "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

{
  "error": "Entity not found"
}

​
401 Unauthorized

{
  "error": "Invalid or missing API key"
}

​
500 Internal Server Error

{
  "error": "Failed to fetch entity"
}

​
Casos de uso

​
Verificación de KYB

Recupera un negocio para verificar su estado KYB antes de aprobar una transacción: 
const company = await fetch(`http://api.gu1.ai/entities/${businessId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(res => res.json());

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

​
Monitoreo de puntuación de riesgo

Verifica la puntuación de riesgo actual y los factores para el monitoreo continuo: 
company = requests.get(
    f'http://api.gu1.ai/entities/{company_id}',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
).json()

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

​
Próximos pasos