Skip to main content
POST
/
entities
/
{entityId}
/
refresh
Refresh Entity
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
}
'

​
Overview

Re-executes marketplace enrichments for an existing person or company, optionally:
  • Updates the entity display name and/or entityData profile (opt-in with new flags)
  • Creates or re-enriches shareholders (companies, depth > 0)
  • Runs the rules engine after enrichment completes
This is the programmatic equivalent of a full dossier refresh from the dashboard (Risk Matrix) or a basic-data-only refresh from Entity Builder.
Backward compatibility: Requests that omit refreshScope, preserveName, and preserveEntityData behave exactly as before: provider selection follows autoExecuteIntegrations, and the entity name is synced from normalized fullName when it changes. entityData is not modified unless you use refreshScope: "basic_data" with preserveEntityData.

​
Endpoint

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

​
Authentication

Requires permission to execute enrichments (same as POST /entities/{entityId}/enrich). 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
entityId
string
required
UUID of the entity to refresh.

​
Request Body

​
Core options

​
forceRefresh
boolean
default:"true"
When true, bypass enrichment cache and call providers again.
​
skipRulesEngine
boolean
default:"false"
When true, skip rules engine execution after enrichments complete.
​
depth
integer
default:"1"
Shareholder / related-entity recursion depth (0–5). Ignored when refreshScope is basic_data (always 0 — root entity only).

​
Provider selection (legacy vs unified scope)

​
autoExecuteIntegrations
object
Legacy provider selection (used when refreshScope is omitted):
  • executeAllActiveEnrichments (boolean)
  • enrichments (array of provider codes)
  • enrichmentGroupRefs (array)
  • excludeEnrichments (array)
Same shape as POST /entities/automatic.
​
autoExecuteIntegrationsShareholders
object
Shareholder pipeline configuration (company dossiers, depth > 0). Same shape as automatic creation.
​
refreshScope
string
Optional unified scope. When set, it replaces autoExecuteIntegrations for choosing root enrichments:
ValueBehavior
basic_dataSingle country-strategy basic-data provider (fresh call). Never processes shareholders.
all_activeAll active marketplace enrichments for the entity type and country.
selectedExplicit list in providerCodes (required, non-empty).
​
providerCodes
array
Required when refreshScope is selected. Ignored otherwise.

​
Safe field sync (opt-in)

​
preserveName
boolean
Controls whether the root entity name is updated after a successful enrichment:
  • true: Keep the current name (recommended for manual review workflows).
  • false: Sync name from provider mapping (basic_data) or normalized fullName (other scopes).
  • Omitted (legacy): Sync name from normalized fullName when it differs — same as pre-2026-06-11 behavior.
​
preserveEntityData
boolean
Only applies when refreshScope is basic_data and enrichment succeeded:
  • Omitted: Do not change entityData (default / legacy).
  • true: Gap-fill — merge provider-mapped profile into entityData without overwriting existing keys (fill empty fields only).
  • false: Replace root entityData with the provider-mapped profile from basic data.
Has no effect for all_active, selected, or legacy bodies without refreshScope: "basic_data".

​
Example Requests

​
Legacy full refresh (unchanged behavior)

curl -X POST http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/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
    }
  }'

​
Safe basic-data refresh (name + profile preserved)

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

​
Basic data + gap-fill profile only

curl -X POST http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/refresh \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshScope": "basic_data",
    "preserveName": true,
    "preserveEntityData": true,
    "skipRulesEngine": true,
    "forceRefresh": true
  }'

​
All active enrichments without renaming

curl -X POST http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/refresh \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshScope": "all_active",
    "preserveName": true,
    "skipRulesEngine": false,
    "depth": 1,
    "autoExecuteIntegrationsShareholders": {
      "executeAllActiveEnrichments": true
    },
    "forceRefresh": true
  }'

​
Response — Success

{
  "success": true,
  "data": {
    "entity": { "id": "...", "name": "...", "entityData": {} },
    "enrichmentResult": { "success": true, "providers": ["..."] },
    "shareholdersUpdated": 0,
    "shareholdersCreated": 0,
    "relationshipsCreated": [],
    "errors": {
      "enrichmentFailed": [],
      "shareholdersFailed": []
    }
  },
  "rulesExecutionSummary": {},
  "executionTimeMs": 4200
}
When skipRulesEngine is false, the response also includes rulesExecutionSummary at the root (same as Analyze Entity).

​
Real-time events

The API emits Socket.IO events on the organization channel:
  • entity:refresh-started
  • entity:refreshed (on success)
  • entity:refresh-failed (on fatal error)

Execute enrichment

Run one or more specific providers without shareholder recursion.

Analyze entity

Rules engine only (optional enrich first).

Materialize relationships

Shareholder chain from normalized data.

Create automatic

Same enrichment + shareholder pipeline for new entities.