Skip to main content
GET
/
entities
Listar empresas
curl --request GET \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>'
{
  "entities": [
    {}
  ]
}

​
Descripción general

Recupera una lista de empresas con filtrado opcional por país, Tax ID o ID externo. Devuelve hasta 100 empresas por solicitud.

​
Endpoint

GET http://api.gu1.ai/entities?type=company

​
Autenticación

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

​
Parámetros de consulta

​
type
string
required
Debe establecerse como company para recuperar solo empresas
​
country
string
Filtrar por código de país ISO 3166-1 alpha-2 (ej., “US”, “BR”, “AR”)
​
taxId
string
Filtrar por número de identificación fiscal exacto
​
externalId
string
Filtrar por tu identificador externo

​
Respuesta

​
entities
array
Array de objetos de empresa, cada uno conteniendo:
  • id - ID interno de gu1
  • externalId - Tu ID externo
  • organizationId - ID de tu organización
  • type - Siempre “company”
  • name - Nombre de la empresa
  • taxId - Tax ID
  • countryCode - Código de país
  • riskScore - Puntuación de riesgo (0-100)
  • riskFactors - Array de factores de riesgo
  • status - Estado de la empresa
  • kycVerified - Estado de verificación KYB
  • kycProvider - Nombre del proveedor KYB
  • kycData - Datos de verificación KYB
  • entityData - Datos específicos de la empresa
  • attributes - Atributos personalizados
  • createdAt - Marca de tiempo de creación
  • updatedAt - Marca de tiempo de última actualización
  • deletedAt - Marca de tiempo de eliminación (null si está activa)

​
Ejemplos

​
Listar todas las empresas

curl -X GET "http://api.gu1.ai/entities?type=company" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Filtrar por país

curl -X GET "http://api.gu1.ai/entities?type=company&country=BR" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Buscar por ID externo

curl -X GET "http://api.gu1.ai/entities?type=company&externalId=business_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Buscar por Tax ID

curl -X GET "http://api.gu1.ai/entities?type=company&taxId=20-12345678-9" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Ejemplo de respuesta

{
  "entities": [
    {
      "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"
        }
      ],
      "status": "active",
      "kycVerified": true,
      "kycProvider": "gueno_ai",
      "kycData": {
        "verificationDate": "2024-10-03T14:30:00Z",
        "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"
      },
      "createdAt": "2024-10-03T14:30:00.000Z",
      "updatedAt": "2024-10-03T14:35:00.000Z",
      "deletedAt": null
    }
  ]
}

​
Casos de uso

​
Monitoreo de negocios de alto riesgo

Consultar todas las empresas y filtrar por puntuación de riesgo: 
const response = await fetch('http://api.gu1.ai/entities?type=company', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const data = await response.json();
const highRiskBusinesses = data.entities.filter(e => e.riskScore > 70);

console.log(`Found ${highRiskBusinesses.length} high-risk businesses requiring review`);
highRiskBusinesses.forEach(company => {
  console.log(`- ${company.name} (Risk: ${company.riskScore})`);
});

​
Panel de cumplimiento KYB

Obtener todos los negocios no verificados para el panel de cumplimiento: 
import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'type': 'company'}
)

companies = response.json()['entities']
unverified = [p for p in companies if not p['kycVerified']]

print(f"Unverified businesses: {len(unverified)}")
for company in unverified:
    print(f"- {company['name']} ({company['externalId']})")

​
Respuestas de error

​
401 Unauthorized

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

​
500 Internal Server Error

{
  "error": "Failed to search entities"
}

​
Límites

  • Resultados máximos por solicitud: 100 empresas
  • Parámetros de consulta: Se pueden combinar para filtrado avanzado
  • Límites de velocidad: Se aplican según tu plan de suscripción

​
Próximos pasos