> ## 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.

# Refresh Entity

> Re-run enrichments for an existing entity with optional shareholder recursion and rules engine — safe scope and preserve flags for name and profile data.

## 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.

<Note>
  **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`.
</Note>

## Endpoint

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

## Authentication

Requires permission to execute enrichments (same as `POST /entities/{entityId}/enrich`).

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField path="entityId" type="string" required>
  UUID of the entity to refresh.
</ParamField>

## Request Body

### Core Options

<ParamField body="forceRefresh" type="boolean" default="true">
  When `true`, bypass enrichment cache and call providers again.
</ParamField>

<ParamField body="skipRulesEngine" type="boolean" default="false">
  When `true`, skip rules engine execution after enrichments complete.
</ParamField>

<ParamField body="depth" type="integer" default="1">
  Shareholder / related-entity recursion depth (**0–5**). Ignored when `refreshScope` is **`basic_data`** (always **0** — root entity only).
</ParamField>

### Provider selection (legacy vs unified scope)

<ParamField body="autoExecuteIntegrations" type="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`](/en/api-reference/entities/create-automatic).
</ParamField>

<ParamField body="autoExecuteIntegrationsShareholders" type="object">
  Shareholder pipeline configuration (company dossiers, `depth` > 0). Same shape as automatic creation.
</ParamField>

<ParamField body="refreshScope" type="string">
  Optional unified scope. When set, it **replaces** `autoExecuteIntegrations` for choosing root enrichments:

  | Value            | Behavior                                                                                |
  | ---------------- | --------------------------------------------------------------------------------------- |
  | **`basic_data`** | Single country-strategy basic-data provider (fresh call). Never processes shareholders. |
  | **`all_active`** | All active marketplace enrichments for the entity type and country.                     |
  | **`selected`**   | Explicit list in `providerCodes` (required, non-empty).                                 |
</ParamField>

<ParamField body="providerCodes" type="array">
  Required when `refreshScope` is **`selected`**. Ignored otherwise.
</ParamField>

### Safe field sync (opt-in)

<ParamField body="preserveName" type="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.
</ParamField>

<ParamField body="preserveEntityData" type="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](/en/api-reference/entities/update)).
  * **`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"`.
</ParamField>

## Example Requests

### Legacy full refresh (unchanged behavior)

```bash theme={null}
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)

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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](/en/api-reference/entities/analyze)).

## 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)

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Execute enrichment" icon="database" href="/en/api-reference/enrichment/execute-by-id">
    Run one or more specific providers without shareholder recursion.
  </Card>

  <Card title="Analyze entity" icon="chart-line" href="/en/api-reference/entities/analyze">
    Rules engine only (optional enrich first).
  </Card>

  <Card title="Materialize relationships" icon="sitemap" href="/en/api-reference/entities/materialize-relationships">
    Shareholder chain from normalized data.
  </Card>

  <Card title="Create automatic" icon="wand-magic-sparkles" href="/en/api-reference/entities/create-automatic">
    Same enrichment + shareholder pipeline for new entities.
  </Card>
</CardGroup>