Skip to main content
POST
http://api.gu1.ai
/
entities
Crear
curl --request POST \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "externalId": "<string>",
  "name": "<string>",
  "countryCode": "<string>",
  "taxId": "<string>",
  "attributes": {},
  "entityData": {}
}
'
{
  "success": true,
  "entity": {}
}

​
Descripción general

Crea una nueva entidad con el tipo y atributos especificados. Las entidades representan los objetos de datos principales que deseas analizar para riesgo y cumplimiento.

​
Endpoint

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

​
Autenticación

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

​
Cuerpo de la solicitud

​
type
string
required
El tipo de entidad a crear. Tipos principales:
  • person - Persona individual/cliente
  • company - Entidad empresarial
  • device - Identificador de dispositivo
  • payment_method - Instrumento de pago
  • location - Ubicación geográfica
  • document - Documento legal
  • account - Cuenta/billetera
  • card - Información de tarjeta
  • alert - Alerta de riesgo/cumplimiento
Nota: Para transacciones, usa el endpoint dedicado de transacciones en su lugar.
​
externalId
string
required
Tu identificador único para esta entidad en tu sistema
​
name
string
required
Nombre para mostrar de la entidad
​
countryCode
string
required
Código de país ISO 3166-1 alfa-2 (ej., “US”, “BR”, “AR”)
​
taxId
string
Número de identificación fiscal (validado según el país)
​
attributes
object
Opcional - Atributos personalizados como pares clave-valor para metadatos flexiblesUsa esto para campos personalizados que no encajan en el esquema estándar (ej: IDs internos, etiquetas, flags)
​
entityData
object
Opcional - Estructura de datos específica del tipo. Ver ejemplos a continuación para cada tipo de entidad.
¿Cuándo usar entityData?
  • Opcional para creación básica de entidad - Puedes crear una entidad con solo type, name, taxId y countryCode
  • Requerido para enriquecimiento y análisis de riesgo - Si quieres ejecutar verificaciones de cumplimiento, necesitarás proporcionar campos relevantes
  • Se puede completar después - Puedes crear una entidad mínima primero, luego actualizarla con datos completos antes de ejecutar el análisis de riesgo
Ejemplo Mínimo (Person):
{
  "type": "person",
  "name": "Juan Pérez",
  "taxId": "12345678",
  "countryCode": "AR"
  // No se necesita entityData para creación básica
}
Ejemplo Completo (Person con datos KYC):
{
  "type": "person",
  "name": "Juan Pérez",
  "taxId": "12345678",
  "countryCode": "AR",
  "entityData": {
    "person": {
      "firstName": "Juan",
      "lastName": "Pérez",
      "dateOfBirth": "1980-01-15",
      "email": "juan@example.com",
      "phone": "+5491123456789"
    }
  }
}

​
Estructuras de datos de entidades

​
Entidad Persona

{
  "person": {
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "YYYY-MM-DD",
    "nationality": "string",
    "occupation": "string",
    "income": number
  }
}

​
Entidad Empresa

{
  "company": {
    "legalName": "string",
    "tradeName": "string",
    "incorporationDate": "YYYY-MM-DD",
    "industry": "string",
    "employeeCount": number,
    "revenue": number
  }
}

​
Entidad Alerta

{
  "alert": {
    "alertNumber": "string",
    "alertType": "RISK | COMPLIANCE | FRAUD | REGULATORY | SYSTEM",
    "severity": "INFO | WARNING | HIGH | CRITICAL",
    "status": "NEW | ACKNOWLEDGED | INVESTIGATING | RESOLVED | FALSE_POSITIVE",
    "sourceSystem": "string",
    "triggerRuleId": "string",
    "triggerCondition": "string",
    "affectedEntityId": "string",
    "relatedEntityIds": ["string"],
    "alertedAt": "ISO8601 timestamp",
    "acknowledgedAt": "ISO8601 timestamp",
    "acknowledgedBy": "string",
    "resolvedAt": "ISO8601 timestamp",
    "resolvedBy": "string",
    "resolutionNotes": "string",
    "falsePositiveReason": "string"
  }
}

​
Respuesta

​
success
boolean
Indica si la entidad se creó correctamente
​
entity
object
El objeto de entidad creado incluyendo:
  • id - ID interno de gu1
  • externalId - Tu ID externo
  • organizationId - ID de tu organización
  • type - Tipo de entidad
  • name - Nombre de la entidad
  • riskScore - Puntuación de riesgo inicial (0-100)
  • status - Estado de la entidad
  • entityData - Datos específicos del tipo
  • attributes - Atributos personalizados
  • createdAt - Marca de tiempo de creación
  • updatedAt - Marca de tiempo de última actualización

​
Ejemplos

​
Crear Entidad Persona (KYC)

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "person",
    "externalId": "customer_12345",
    "name": "María González",
    "countryCode": "AR",
    "taxId": "20-12345678-9",
    "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"
    }
  }'

​
Crear Entidad Empresa (KYB)

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "company",
    "externalId": "company_789",
    "name": "Tech Solutions S.A.",
    "countryCode": "BR",
    "taxId": "12.345.678/0001-90",
    "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"
    }
  }'

​
Ejemplo de respuesta

{
  "success": true,
  "entity": {
    "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,
    "status": "active",
    "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"
    },
    "createdAt": "2024-10-03T14:30:00.000Z",
    "updatedAt": "2024-10-03T14:30:00.000Z"
  }
}

​
Respuestas de Error

​
400 Bad Request - ID Fiscal Inválido

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Formato de CUIT inválido. Por favor verifica el formato e intenta nuevamente.",
    "details": {
      "field": "taxId",
      "taxIdName": "CUIT",
      "providedValue": "20-12345678-9"
    }
  },
  "entity": null
}

​
400 Bad Request - Campos Requeridos Faltantes

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Faltan campos requeridos para la creación de la empresa",
    "details": {
      "missingFields": ["legalName", "industry"],
      "requiredFields": ["legalName", "tradeName", "industry", "incorporationDate"],
      "countryCode": "BR"
    }
  },
  "entity": null
}

​
409 Conflict - Entidad Duplicada

{
  "success": false,
  "error": {
    "code": "DUPLICATE_ENTITY",
    "message": "Ya existe una entidad con este external_id",
    "details": {
      "field": "external_id",
      "value": "customer_12345",
      "constraint": "entities_organization_external_id_unique"
    }
  },
  "entity": null
}

​
401 Unauthorized

{
  "error": "Invalid or missing API key",
  "code": "INVALID_KEY"
}

​
429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Has excedido tu límite de velocidad de la API. Por favor espera antes de hacer más solicitudes.",
  "retryAfter": 3600,
  "limit": 100,
  "remaining": 0,
  "resetAt": "2025-01-15T10:00:00Z"
}

​
500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Ocurrió un error inesperado al crear la entidad",
    "details": {
      "message": "Database connection timeout"
    }
  },
  "entity": null
}

​
Próximos pasos

Después de crear una entidad, puedes:
  1. Solicitar análisis de IA - Obtener evaluación de riesgo automatizada
  2. Listar entidades - Consultar tus entidades
  3. Obtener detalles de entidad - Recuperar información completa de la entidad
  4. Aplicar reglas - Ejecutar reglas de cumplimiento y riesgo