Skip to main content
POST
Materialize relationships

Overview

Materializes relationships and related entities for an existing person or company using the latest row in normalized_enrichment. Typical use cases:
  • Brazil β€” company: create/update the shareholder chain (QSA) from normalized data.
  • Brazil β€” person: create/update related companies and related persons from normalized data.
The endpoint can optionally re-run enrichments on the root dossier first (runEnrichmentFirst): only the country strategy provider(s) needed to refresh shareholders/relationships in normalized data (not the full marketplace list). Root enrichment always requests fresh provider data for that step. Then it runs the same style of shareholder/related-entity pipeline as automatic creation.
The entity must be company or person. Other types return 400. The dossier country must have an automatic-creation strategy (today this flow is primarily used for Brazil; other countries may return 400 if defaults are missing or depth/providers are invalid).

Endpoint

Authentication

Requires a valid API key:

Path Parameters

entityId
string
required
UUID of the root entity (person or company) whose relationships you want to materialize.

Request Body

runEnrichmentFirst
boolean
default:"false"
When true, the API re-executes on the root dossier only the enrichment provider(s) the country strategy requires for that entity type to populate shareholders/relationships in normalized data (e.g. Brazil company vs person). It does not run all marketplace enrichments on the root.When false, a normalized_enrichment row must already exist for the entity; otherwise the API returns 422 (NO_NORMALIZED_ENRICHMENT).
depth
integer
default:"1"
How many levels of shareholders or related entities to process. Allowed range 0–5 (schema default 1).
autoExecuteIntegrationsShareholders
object
Same shape as POST /entities/automatic β†’ autoExecuteIntegrationsShareholders: executeAllActiveEnrichments, enrichments: { company, person }, optional enrichmentGroupRefs, and excludeEnrichments (applied to both company and person lists). Ignored when executeOnlyRootData is true.
executeOnlyRootData
boolean
default:"false"
When true, each new child is created from the root dossier normalized data only (name + tax ID) and no child integration pipeline runs (autoExecuteIntegrationsShareholders is not applied). Applies to company (QSA shareholders) and person dossiers in Brazil (related companies/persons from normalized). Cannot be combined with a non-empty autoExecuteIntegrationsShareholders pipeline.
runInBackground
boolean
default:"true"
When true (default), the API returns 202 immediately with data.status: "processing" and runs enrichment, materialization, and optional risk matrix on the server. Completion is signaled over Socket.IO (see below).When false, the server waits for the full pipeline and returns 200 with counts and flags in data.
riskMatrix
object
Optional. After the pipeline finishes, run the rules / risk matrix on the root entity only.
  • execute (boolean, required when the object is sent): set true to run the matrix after materialization.
  • riskMatrixId (UUID | null, optional): null or omitted β†’ use the matrix assigned to the entity; a UUID β†’ run that matrix for this execution only (override, does not change the entity row).
refreshEnrichShareholders
boolean
When true, if a discovered child entity (shareholder / related company or person) already exists in your org (same tax ID), the pipeline re-runs configured enrichments for that child instead of skipping refresh.

Async behavior (default): HTTP 202 + Socket.IO

When runInBackground is true, the response is 202:
Subscribe to your existing Socket.IO connection (same as the dashboard). Events: After completion, refetch the entity, relationships, and list endpoints as needed (e.g. GET /entities/:id, list queries).

Synchronous response (runInBackground: false): HTTP 200

If the materialization step finishes with a pipeline warning (e.g. partial graph), success may be true while data.error carries a human-readable messageβ€”check both.

Example: Brazil company, async + risk matrix

Example: use a specific matrix once (override)

Error responses (selection)

See Also