5. Golden records and review

A Golden record is the single, combined version of one real-world thing, such as a customer or an invoice, built from the records your connected systems hold about it. Each value records which system it came from.

Changes to Golden records do not apply silently. They arrive as proposed changes, and a person or an approval policy decides them.

In the API a Golden record is identified by its entityClusterId.

Read Golden records

In the app, open Golden records.

From the API:

curl "https://api.inferrex.com/v1/unified/records?entity_type=customer" \
  -H "X-API-Key: $INFERREX_API_KEY"

Shape of one record:

{
  id: string;
  entity_cluster_id: string;
  entity_type: string;
  version: number;
  data: Record<string, unknown>;
  source_attribution: Record<string, {
    provider: string;
    connectionId: string;
    externalId?: string;
    recordVersion: number;
    observedAt: string;
    strategy?: string;
    ruleApplied?: boolean;
    confidence?: number;
    contested?: boolean;
  }>;
  quality_score: string;
  field_count: number;
  source_count: number;
  redacted_fields: string[];
}

Decide which system is trusted

Every rule and role is keyed by the system's own connection id. Two accounts with the same vendor are two independent systems.

Source of truth

For each kind of Golden record, each system has a role: system_of_record, contributor, reference or receiver.

curl https://api.inferrex.com/v1/golden-records/source-roles \
  -H "X-API-Key: $INFERREX_API_KEY"

The answer lists, for each kind, the systems that supply it or receive it, each with its role in force, who set it, Inferrex's recommendation with reasons from your own data, and any change waiting for approval.

Set a role:

curl -X POST https://api.inferrex.com/v1/golden-records/source-roles \
  -H "X-API-Key: $INFERREX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connectionId": "CONNECTION_ID", "entityType": "customer", "role": "system_of_record", "choice": "confirm"}'

choice is confirm (the role you send), choose (another role) or not_sure (use Inferrex's recommendation, kept as unconfirmed). The change applies at once unless your workspace has an approval policy for source-of-truth changes and the change's risk is above it. Then it waits for approval and the role in force keeps deciding.

Field rules

With no rule for a field, the source of truth's own value wins. To decide one field differently, create a field authority rule at /v1/field-authority-rules with an entity_type, a field_name and a strategy: provider_wins, freshest, most_complete, most_accurate or manual.

A starting setup

GET /v1/golden-records/setup-suggestion suggests a starting setup worked out from the Golden records and proposed changes you already have. POST /v1/golden-records/setup-suggestion/apply applies it. Read the suggestion before you apply it.

Decide proposed changes

In the app, proposed changes are at Golden records, Changes, and in Review under Golden-record changes.

List the ones waiting:

curl "https://api.inferrex.com/v1/canonical-proposals?status=pending" \
  -H "X-API-Key: $INFERREX_API_KEY"

A proposal's status is pending, approved, rejected or expired. Each carries a risk_level, the field_diffs it would make (fieldName, changeType, oldValue, newValue) and any conflicts between systems.

Read one in full before you decide: GET /v1/canonical-proposals/:id.

Approve:

curl -X POST https://api.inferrex.com/v1/canonical-proposals/PROPOSAL_ID/approve \
  -H "X-API-Key: $INFERREX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Checked against the source record"}'

Reject (a reason is required, and nothing is written):

curl -X POST https://api.inferrex.com/v1/canonical-proposals/PROPOSAL_ID/reject \
  -H "X-API-Key: $INFERREX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "The older address is the correct one"}'

What approval does:

• When approvers are required, your approval is recorded and the change stays pending until every required approver has approved.
• The final approval applies it. Inferrex writes the Golden record and sends the change back to the systems it came from.
• 403 means your role and teams fill none of the approver places still open.
• 409 means you have already approved it, it is no longer pending, or it is out of date. When a newer proposal exists for the same record, details.newerProposalId names it. Review that one instead.

POST /v1/canonical-proposals/bulk-approve approves several at once. Its answer says how many were approved, which still need other approvers, and which were skipped because applying them would roll a record back. Use it only for changes you have read.

Who must approve

Approval policies live at /v1/approval-policies and in the app at Workspace settings, Approval policies. A policy names the kind of change (entity_type), the conditions under which a change is approved automatically (auto_approve_conditions) and the required_approvers.

Merge, split, restore and archive

Edits to a Golden record are previewed, then proposed, then approved like any other change.

1. Preview:

   curl -X POST https://api.inferrex.com/v1/golden-records/ENTITY_CLUSTER_ID/edit-preview \
     -H "X-API-Key: $INFERREX_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"kind": "merge", "otherId": "OTHER_ENTITY_CLUSTER_ID"}'
   

   kind is merge, split, restore or archive. A split takes move: the source records to move out, as /sources lists them. When the edit cannot be done, allowed is false and refusal.message says why.

2. Propose: POST /v1/golden-records/:entityClusterId/edits with the same body and an optional note. The answer is { proposalId, status, riskLevel, riskReasons }.

3. Decide it with the approve or reject call above.

A merge can be split back, a split merged back, and a restore archived again, each by another edit.

Send a Golden record back to its systems

POST /v1/golden-records/:entityClusterId/sync sends a Golden record's values back to the systems it was built from, so they all agree. Send { "fields": [...] } to limit it to particular fields. This writes to your systems. It runs in the background, and the answer says how many systems and fields it is updating.

Archived records and deletes

Golden records Inferrex no longer builds are archived, not deleted: GET /v1/golden-records/archived. Each system has a delete choice for what happens when a source deletes a record: keep, mark_deleted, delete_now or retention (PUT /v1/connections/:id/source-delete-action). GET /v1/golden-records/deletions lists the deletes passed on to destinations.

Review

Review is one queue for every decision that waits for a person. Its tabs are Safety stops, Sign-ins, Failed writes, Repair questions, Golden-record changes and Approvals.

From the API, the same items come from these routes:

To say who is looking at an item: PUT /v1/workspace/review-assignments with { "itemKind": "...", "itemId": "...", "assignee": "me" }. Nothing about the item itself changes.

Chapter 6 explains safety stops, failed writes and repairs.

Next: watch and health.