Skip to main content
POST
/
entities
/
{entityId}
/
refresh
Actualizar entidad (refresh)
curl --request POST \
  --url http://api.gu1.ai/entities/{entityId}/refresh \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "forceRefresh": true,
  "skipRulesEngine": true,
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "refreshScope": "<string>",
  "providerCodes": [
    {}
  ],
  "preserveName": true,
  "preserveEntityData": true
}
'

​
Descripción

Re-ejecuta enrichments del marketplace para una persona o empresa existente, opcionalmente:
  • Actualiza el nombre y/o entityData (solo si lo indicás con los nuevos flags)
  • Crea o re-enriquece socios (empresas, depth > 0)
  • Ejecuta el motor de reglas al finalizar
Equivalente programático al refresh completo del panel (Risk Matrix) o al refresh solo datos básicos del Entity Builder.
Retrocompatibilidad: Si omitís refreshScope, preserveName y preserveEntityData, el comportamiento es el de siempre: la selección de proveedores sigue autoExecuteIntegrations y el nombre se sincroniza desde fullName normalizado cuando cambia. entityData no se modifica salvo refreshScope: "basic_data" con preserveEntityData.

​
Endpoint

POST http://api.gu1.ai/entities/{entityId}/refresh

​
Autenticación

Requiere permiso para ejecutar enrichments (igual que POST /entities/{entityId}/enrich).

​
Parámetros de ruta

​
entityId
string
required
UUID de la entidad a actualizar.

​
Cuerpo

​
forceRefresh
boolean
default:"true"
Si es true, omite caché y vuelve a llamar a los proveedores.
​
skipRulesEngine
boolean
default:"false"
Si es true, no ejecuta reglas después del enrichment.
​
depth
integer
default:"1"
Profundidad de socios (0–5). Ignorado con refreshScope: "basic_data" (siempre 0).
​
autoExecuteIntegrations
object
Selección legacy de proveedores (cuando refreshScope se omite). Misma forma que POST /entities/automatic.
​
autoExecuteIntegrationsShareholders
object
Pipeline de socios (empresas, depth > 0). Misma forma que creación automática.
​
refreshScope
string
Scope unificado opcional. Si está presente, reemplaza autoExecuteIntegrations en la entidad raíz:
ValorComportamiento
basic_dataUn solo proveedor de datos básicos del país (llamada fresh). Sin socios.
all_activeTodos los enrichments activos para tipo y país.
selectedLista explícita en providerCodes (obligatorio, no vacío).
​
providerCodes
array
Obligatorio cuando refreshScope es selected.
​
preserveName
boolean
  • true: conservar el nombre actual.
  • false: sincronizar desde mapeo (basic_data) o fullName normalizado.
  • Omitido (legacy): sincronizar nombre si fullName cambió (comportamiento anterior).
​
preserveEntityData
boolean
Solo con refreshScope: "basic_data" y enrichment exitoso:
  • Omitido: no tocar entityData.
  • true: completar solo campos vacíos (gap-fill).
  • false: reemplazar entityData desde datos básicos.
Sin efecto en all_active, selected o bodies legacy sin basic_data.

​
Ejemplos

​
Refresh legacy (sin cambios)

curl -X POST http://api.gu1.ai/entities/{entityId}/refresh \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skipRulesEngine": false,
    "depth": 1,
    "forceRefresh": true,
    "autoExecuteIntegrations": { "executeAllActiveEnrichments": true },
    "autoExecuteIntegrationsShareholders": { "executeAllActiveEnrichments": true }
  }'

​
Solo datos básicos (seguro)

curl -X POST http://api.gu1.ai/entities/{entityId}/refresh \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshScope": "basic_data",
    "preserveName": true,
    "skipRulesEngine": true,
    "forceRefresh": true
  }'

​
Respuesta

Incluye data.entity, data.enrichmentResult, contadores de socios y errors. Con skipRulesEngine: false, también rulesExecutionSummary en la raíz (igual que Analyze).

​
Eventos Socket.IO

entity:refresh-started, entity:refreshed, entity:refresh-failed.

​
Endpoints relacionados

Analyze

Motor de reglas (enrichment opcional).

Materializar relaciones

Cadena de socios desde normalized.