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_bodyAPI Reference
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.
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_bodyOverview
Re-executes marketplace enrichments for an existing person or company, optionally:- Updates the entity display name and/or
entityDataprofile (opt-in with new flags) - Creates or re-enriches shareholders (companies,
depth> 0) - Runs the rules engine after enrichment completes
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 asPOST /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)
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 normalizedfullName(other scopes).- Omitted (legacy): Sync name from normalized
fullNamewhen 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 intoentityDatawithout overwriting existing keys (fill empty fields only).false: Replace rootentityDatawith the provider-mapped profile from basic data.
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
}
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-startedentity:refreshed(on success)entity:refresh-failed(on fatal error)
Related Endpoints
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.
Was this page helpful?