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
}
'

import requests

url = "http://api.gu1.ai/entities/{entityId}/refresh"

payload = {
    "forceRefresh": True,
    "skipRulesEngine": True,
    "depth": 123,
    "autoExecuteIntegrations": {},
    "autoExecuteIntegrationsShareholders": {},
    "refreshScope": "<string>",
    "providerCodes": [{}],
    "preserveName": True,
    "preserveEntityData": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    forceRefresh: true,
    skipRulesEngine: true,
    depth: 123,
    autoExecuteIntegrations: {},
    autoExecuteIntegrationsShareholders: {},
    refreshScope: '<string>',
    providerCodes: [{}],
    preserveName: true,
    preserveEntityData: true
  })
};

fetch('http://api.gu1.ai/entities/{entityId}/refresh', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/{entityId}/refresh",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'forceRefresh' => true,
    'skipRulesEngine' => true,
    'depth' => 123,
    'autoExecuteIntegrations' => [
        
    ],
    'autoExecuteIntegrationsShareholders' => [
        
    ],
    'refreshScope' => '<string>',
    'providerCodes' => [
        [
                
        ]
    ],
    'preserveName' => true,
    'preserveEntityData' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/{entityId}/refresh"

	payload := strings.NewReader("{\n  \"forceRefresh\": true,\n  \"skipRulesEngine\": true,\n  \"depth\": 123,\n  \"autoExecuteIntegrations\": {},\n  \"autoExecuteIntegrationsShareholders\": {},\n  \"refreshScope\": \"<string>\",\n  \"providerCodes\": [\n    {}\n  ],\n  \"preserveName\": true,\n  \"preserveEntityData\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities/{entityId}/refresh")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"forceRefresh\": true,\n  \"skipRulesEngine\": true,\n  \"depth\": 123,\n  \"autoExecuteIntegrations\": {},\n  \"autoExecuteIntegrationsShareholders\": {},\n  \"refreshScope\": \"<string>\",\n  \"providerCodes\": [\n    {}\n  ],\n  \"preserveName\": true,\n  \"preserveEntityData\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/{entityId}/refresh")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"forceRefresh\": true,\n  \"skipRulesEngine\": true,\n  \"depth\": 123,\n  \"autoExecuteIntegrations\": {},\n  \"autoExecuteIntegrationsShareholders\": {},\n  \"refreshScope\": \"<string>\",\n  \"providerCodes\": [\n    {}\n  ],\n  \"preserveName\": true,\n  \"preserveEntityData\": true\n}"

response = http.request(request)
puts response.read_body

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
}
'

import requests

url = "http://api.gu1.ai/entities/{entityId}/refresh"

payload = {
    "forceRefresh": True,
    "skipRulesEngine": True,
    "depth": 123,
    "autoExecuteIntegrations": {},
    "autoExecuteIntegrationsShareholders": {},
    "refreshScope": "<string>",
    "providerCodes": [{}],
    "preserveName": True,
    "preserveEntityData": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    forceRefresh: true,
    skipRulesEngine: true,
    depth: 123,
    autoExecuteIntegrations: {},
    autoExecuteIntegrationsShareholders: {},
    refreshScope: '<string>',
    providerCodes: [{}],
    preserveName: true,
    preserveEntityData: true
  })
};

fetch('http://api.gu1.ai/entities/{entityId}/refresh', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/{entityId}/refresh",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'forceRefresh' => true,
    'skipRulesEngine' => true,
    'depth' => 123,
    'autoExecuteIntegrations' => [
        
    ],
    'autoExecuteIntegrationsShareholders' => [
        
    ],
    'refreshScope' => '<string>',
    'providerCodes' => [
        [
                
        ]
    ],
    'preserveName' => true,
    'preserveEntityData' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/{entityId}/refresh"

	payload := strings.NewReader("{\n  \"forceRefresh\": true,\n  \"skipRulesEngine\": true,\n  \"depth\": 123,\n  \"autoExecuteIntegrations\": {},\n  \"autoExecuteIntegrationsShareholders\": {},\n  \"refreshScope\": \"<string>\",\n  \"providerCodes\": [\n    {}\n  ],\n  \"preserveName\": true,\n  \"preserveEntityData\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities/{entityId}/refresh")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"forceRefresh\": true,\n  \"skipRulesEngine\": true,\n  \"depth\": 123,\n  \"autoExecuteIntegrations\": {},\n  \"autoExecuteIntegrationsShareholders\": {},\n  \"refreshScope\": \"<string>\",\n  \"providerCodes\": [\n    {}\n  ],\n  \"preserveName\": true,\n  \"preserveEntityData\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/{entityId}/refresh")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"forceRefresh\": true,\n  \"skipRulesEngine\": true,\n  \"depth\": 123,\n  \"autoExecuteIntegrations\": {},\n  \"autoExecuteIntegrationsShareholders\": {},\n  \"refreshScope\": \"<string>\",\n  \"providerCodes\": [\n    {}\n  ],\n  \"preserveName\": true,\n  \"preserveEntityData\": true\n}"

response = http.request(request)
puts response.read_body

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

string

required

UUID of the entity to refresh.

Request Body

Core Options

boolean

default:"true"

When true, bypass enrichment cache and call providers again.

boolean

default:"false"

When true, skip rules engine execution after enrichments complete.

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)

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.

object

Shareholder pipeline configuration (company dossiers, depth > 0). Same shape as automatic creation.

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

array

Required when refreshScope is selected. Ignored otherwise.

Safe field sync (opt-in)

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.

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.

Update entity attributes Analyze Entity

⌘I

​Overview

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Core Options

​Provider selection (legacy vs unified scope)

​Safe field sync (opt-in)

​Example Requests

​Legacy full refresh (unchanged behavior)

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

​Basic data + gap-fill profile only

​All active enrichments without renaming

​Response — Success

​Real-Time Events

​Related Endpoints

Execute enrichment

Analyze entity

Materialize relationships

Create automatic

Overview

Endpoint

Authentication

Path Parameters

Request Body

Core Options

Provider selection (legacy vs unified scope)

Safe field sync (opt-in)

Example Requests

Legacy full refresh (unchanged behavior)

Safe basic-data refresh (name + profile preserved)

Basic data + gap-fill profile only

All active enrichments without renaming

Response — Success

Real-Time Events

Related Endpoints