Skip to main content
POST
Crear una entidad (persona o empresa)

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

Autenticación

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

Cuerpo de la solicitud

string
required
El tipo de entidad a crear. Tipos disponibles:
  • person - Persona individual/cliente
  • company - Entidad empresarial
string
Tu identificador único para esta entidad en tu sistema. Opcional — gu1 asigna uno automáticamente si se omite (ver tabla abajo).
string
required
Nombre para mostrar de la entidad
string
required
Código de país ISO 3166-1 alfa-2 (ej., “US”, “BR”, “AR”)
string
Número de identificación fiscal (validado según el país). En una organización, un taxId activo normalizado puede pertenecer a una sola entidad (person o company). Los conflictos responden 409 con código DUPLICATE_TAX_ID.
Cuando se omite externalIdEl campo taxId se sigue guardando en el formato de visualización del país cuando lo envías. Mandá un externalId explícito si necesitás tu propio ID de CRM o usuario, independiente del documento fiscal.
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.
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.
object | null
Horario operativo opcional para reglas KYT (outside_entity_operational_hours). Campo en raíz (no dentro de attributes).
  • timezone (obligatorio si se envía operationalHours): valor del enum transaction_time_zone. Lista completa: Enum zona horaria.
  • weekly: claves mondaysunday. Cada día: { "start": "09:00", "end": "18:00" } o { "closed": true }. Días omitidos = cerrado.
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.
object
Opcional. Pide que un enriquecimiento que admite monitoreo corra en modo lista vigilada (op 1: screening + alta en watchlist para corridas periódicas), no solo como consulta puntual (op 0).Alcance hoy: solo global_gueno_sanctions_enrichment. La clave del mapa es el mismo código que en autoExecuteIntegrations.enrichments. Los códigos legacy *_check fueron eliminados (2026-06-04) y ya no forman parte del contrato.
  • main: flags para la entidad principal de este POST /entities.
  • relationships: ignorado aquí; usá Crear automáticamente con depth > 0.
Valor por código (recomendado objeto; la API acepta también boolean legacy):
  • { "watchlist": true } — suscripción; matriz de monitoreo = heredar riskMatrixId de la entidad.
  • { "watchlist": true, "riskMatrixId": "<uuid>" } — suscripción; solo esa matriz en reglas/screening disparados por monitoreo.
  • { "watchlist": false } o false — sin lista vigilada.
  • true — equivalente a { "watchlist": true }.
Requisitos (si falta alguno, el enrichment corre igual como consulta normal, sin error obligatorio): (1) el código en autoExecuteIntegrations.enrichments o activo vía execute-all; (2) monitoreo habilitado en Marketplace para Gu1 sanciones.Guía: Monitoreo de sanciones Gu1. Ejemplos: Monitoreo al crear.
object
Opcional — Ejecutar integraciones (enriquecimientos y checks) justo después de crear la entidad.Propiedades:
  • executeAllActiveEnrichments (boolean)
  • enrichments (array de códigos de proveedor; ver códigos de proveedor)
  • enrichmentGroupRefs (array de strings, opcional) — Slugs de grupos de enriquecimiento del Marketplace (solo enriquecimientos). Con executeAllActiveEnrichments: false, se resuelven y se combinan con enrichments explícitos. Con executeAllActiveEnrichments: true, los refs de grupo no se usan; los enrichments explícitos pueden seguir añadiendo códigos tras el conjunto activo.
object
Opcional — Atributos personalizados. Acepta formato plano ({ "phone": "..." }) o anidado por categoría ({ "contact": { "phone": "..." } }). Se almacenan tal cual (los objetos anidados actúan como categorías y se devuelven como se enviaron); ver Actualizar entidad para detalles.
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):
Ejemplo Completo (Person con datos KYC):

Matriz de riesgo y ejecución de reglas

string | string[]
Uno o más UUIDs de matrices de riesgo (legacy: un solo UUID). Si se envían, tras la creación el sistema evalúa la entidad solo contra reglas activas de esas matrices (salvo skipRulesExecution: true). Misma semántica que riskMatrixIds cuando enviás un único id como string.
string[]
Forma preferida para varias matrices: lista ordenada de UUIDs de tu organización. Si viene informada y no vacía, tiene precedencia sobre riskMatrixId.
boolean
default:"false"
Omitir la ejecución automática de reglas tras crear la entidad. Usalo para crear primero y disparar reglas manualmente después.
number
default:"0"
Solo entidades company: niveles de accionistas a crear automáticamente (0–5). 0 = ninguno (default).
array
Vínculos declarativos a entidades ya existentes en la misma organización (máx. 10). Independiente de shareholderDepth / enrichment.Cada ítem debe incluir exactamente uno de: relatedEntityId (UUID), relatedTaxId, relatedExternalId.Si la contraparte no existe → 404 RELATED_ENTITY_NOT_FOUND y no se crea la entidad.

Estructuras de datos de entidades

Entidad Persona

Género (entityData.person.gender) — enum cerrado. Solo se aceptan los valores de la tabla; cualquier otro string (p. ej. X, non_binary) devuelve error de validación.Argentina (AR): la derivación automática de CUIL desde DNI + género y las validaciones RENAPER solo reconocen M/F (o male/female). Con other o unknown no se deriva CUIL y RENAPER no puede usar el género de la entidad.

Entidad Empresa

Entidad Alerta

Parámetros de Query

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:
Nota: El re-enriquecimiento puede incurrir en costos adicionales de proveedores de datos externos.

Respuesta

boolean
Indica si la entidad se creó correctamente
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
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.
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 Gu1 al crear

El parámetro monitoring no ejecuta integraciones por sí solo: solo modifica cómo corre un enrichment que ya pediste en autoExecuteIntegrations. Hoy solo aplica a integraciones del catálogo con monitoreo de org (Marketplace); en creación por API el caso documentado es global_gueno_sanctions_enrichment.
Los códigos *_check (p. ej. global_gueno_sanctions_check) fueron eliminados (2026-06-04). Para lista vigilada al crear, usá global_gueno_sanctions_enrichment en enrichments y el mismo código en monitoring.main.

Solo lista vigilada Gu1 (persona)

Enriquecimientos locales + monitoreo Gu1 (persona AR)

Mismo POST /entities: podés combinar enrichments de registro/KYC con Gu1 en lista vigilada. monitoring solo afecta al código que figure en el mapa (acá, Gu1 sanciones).
Los enrichments ar_renaper_* y ar_repet_* corren como consulta normal; solo global_gueno_sanctions_enrichment puede pasar a op 1 si el monitoreo está habilitado en Marketplace.

Matriz de riesgo solo para monitoreo (opcional)

Si además de riskMatrixId en la entidad querés una matriz distinta solo para reglas disparadas por el screening diario:
riskMatrixId: null en el objeto equivale a heredar la matriz global de la entidad para esas corridas.

Empresa (type: "company")

Misma forma en monitoring.main; cambiá type, entityData.company y los códigos de enrichments según el país.
monitoring.relationships no se usa en POST /entities. Para accionistas o relacionadas en el mismo job, usá Crear automáticamente con depth > 0, monitoring.relationships y los enrichments correspondientes en autoExecuteIntegrationsShareholders.

Ejemplos

Crear Entidad Persona (KYC)

Crear Entidad Empresa (KYB)

Ejemplo de respuesta

Respuestas de Error

400 Bad Request - ID Fiscal Inválido

400 Bad Request - Campos Requeridos Faltantes

409 Conflict - Entidad Duplicada

Un tax ID duplicado (misma organización, cualquier tipo de entidad) responde DUPLICATE_TAX_ID con existingEntityId / existingEntityType en details cuando están disponibles.

401 Unauthorized

429 Too Many Requests

500 Internal Server Error

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