Skip to main content
POST
/
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>",
  "email": {},
  "phone": {},
  "nationality": {},
  "monitoring": {},
  "attributes": {},
  "entityData": {}
}
'
{
  "success": true,
  "entity": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

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.

​
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 disponibles:
  • person - Persona individual/cliente
  • company - Entidad empresarial
​
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)
​
email
string | null
Correo de contacto principal en la fila de la entidad (opcional, nullable). Las entidades existentes quedan en null hasta que se envíe un valor. En PATCH, null borra el valor.
​
phone
string | null
Teléfono de contacto principal en la fila de la entidad (opcional, nullable). Las entidades existentes quedan en null hasta que se envíe un valor. En PATCH, null borra el valor.
​
nationality
string | null
Nacionalidad opcional en raíz: ISO 3166-1 alfa-2 o una etiqueta reconocida que la API mapea a ISO2. Si se omite, el campo raíz puede derivarse de entityData.person.nationality o entityData.company.nationality cuando sea mapeable.
​
monitoring
object
Opcional: activa modo lista de seguimiento (Regtia op 1) para enriquecimientos concretos de la entidad principal cuando se ejecutan vía autoExecuteIntegrations. Solo tiene efecto si la organización tiene el monitoreo activado en Marketplace para esa integración.
  • main (objeto, opcional): mapa código de proveedor del enriquecimiento → boolean. Hoy el único código soportado es global_gueno_sanctions_enrichment (sanciones globales Gueno).
  • relationships (objeto, opcional): no aplica en este endpoint; usar Crear automáticamente con depth > 0 y monitoring.relationships para accionistas/relacionadas.
Si el monitoreo en la org no está activo, el enriquecimiento sigue como consulta normal (op 0). El enriquecimiento debe figurar también en autoExecuteIntegrations.enrichments (o ejecutarse con executeAllActiveEnrichments: true si está activo).
​
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"
  }
}

​
Parámetros de Query

​
refresh
boolean
default:"false"
Fuerza el re-enriquecimiento de la entidad incluso si ya existe en el sistema.Tipo: boolean (query string: "true" o "false")Comportamiento:
  • Cuando es true: Fuerza al sistema a obtener datos frescos de proveedores de enriquecimiento (ej: verificación de antecedentes, datos KYC, registros de empresas)
  • Cuando es false u omitido: Utiliza datos de enriquecimiento en caché si están disponibles
  • Sobreescribe la configuración de organización enrichmentsConfig.reEnrichExistingEntities
Casos de Uso:
  • Re-validar datos de entidad después de un período de tiempo significativo
  • Actualizar información cuando se sabe que los datos externos han cambiado
  • Actualización manual activada por el equipo de cumplimiento
  • Auditorías periódicas de calidad de datos
Ejemplo:
POST http://api.gu1.ai/entities?refresh=true
Nota: El re-enriquecimiento puede incurrir en costos adicionales de proveedores de datos externos.

​
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
​
rulesResult
object
Resultado de la ejecución de reglas (solo presente cuando se ejecutaron reglas, p. ej. cuando skipRulesExecution es false y hay matriz de riesgo configurada), incluyendo:
  • success (boolean) - Si las reglas se ejecutaron correctamente
  • rulesTriggered (number) - Número de reglas disparadas
  • alerts (array) - Alertas generadas por las reglas
  • riskScore (number) - Puntuación de riesgo final
  • decision (string) - Decisión final (APPROVE, REJECT, HOLD, REVIEW_REQUIRED)
  • rulesExecutionSummary (object) - Presente cuando se ejecutaron reglas. Ver abajo la estructura.
​
rulesExecutionSummary
object
Solo presente cuando se ejecutaron reglas (p. ej. skipRulesExecution es false). Resumen de qué reglas hicieron match (hit) vs no (no hit), acciones ejecutadas y puntuación total. Omitido cuando las reglas no se ejecutaron.
  • rulesHit (array) - Reglas cuyas condiciones se cumplieron. Cada ítem: name, description, score, priority, category, status (p. ej. active, shadow), conditions (array de { field, value, operator? }), actions (alerts, suggestion, status, assignedUser).
  • rulesNoHit (array) - Reglas evaluadas pero cuyas condiciones no se cumplieron. Misma estructura que rulesHit (incluye acciones configuradas, no ejecutadas).
  • actionsExecuted (object) - Acciones ejecutadas agregadas de todas las reglas que hicieron hit: alerts (array de { name?, type?, severity?, description? }), suggestion (BLOCK | SUSPEND | FLAG, mayor peso), status (estado aplicado a la entidad, si hay), assignedUser ({ userId }, si hay), customKeys (array de strings, opcional) — claves de acciones personalizadas de las reglas que hicieron match; para integraciones/workflows.
  • totalScore (number) - Suma del score de todas las reglas que hicieron hit y no están en estado shadow.

​
Ejemplo: monitoreo de sanciones Gueno al crear

Sirve cuando querés que el enriquecimiento de sanciones globales Gueno corra en modo lista vigilada (alta para screening diario) en el mismo POST /entities, y no solo como consulta puntual.
monitoring no hace nada salvo que:
  1. El mismo código de enriquecimiento esté en autoExecuteIntegrations.enrichments (o uses executeAllActiveEnrichments: true y ese enriquecimiento esté activo), y
  2. La organización tenga monitoreo habilitado para Gueno sanciones en Marketplace. Si no, el enriquecimiento corre como screening normal (op 0).

​
Persona (type: "person")

{
  "type": "person",
  "externalId": "cust_screening_001",
  "name": "María González",
  "countryCode": "AR",
  "taxId": "27-12345678-1",
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15",
      "nationality": "AR"
    }
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": true
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "executeAllActiveChecks": false,
    "enrichments": ["global_gueno_sanctions_enrichment"],
    "checks": []
  }
}

​
Empresa (type: "company")

{
  "type": "company",
  "externalId": "co_screening_001",
  "name": "Tech Solutions S.A.",
  "countryCode": "AR",
  "taxId": "30-71000001-2",
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "tradeName": "Tech Solutions",
      "industry": "Software"
    }
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": true
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "executeAllActiveChecks": false,
    "enrichments": ["global_gueno_sanctions_enrichment"],
    "checks": []
  }
}
La clave relationships dentro de monitoring no se usa en POST /entities. Para accionistas o entidades relacionadas creadas en el mismo flujo, usá Crear automáticamente con depth > 0 y monitoring.relationships.

​
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