Skip to main content

Golden Records

Read the latest run and the multi-source records of a domain, then open one golden record with surviving values, sources, conflicts and merge reasons.

GET /v1/master-records/{domain}/overview returns the latest run with its statistics and one page of the records that have two or more members. The page is ordered review first, then by conflict severity and lowest score. Single-source records are not listed; they are in the crosswalk and in the run statistics. run is null when the domain has never run.

GET/v1/master-records/{domain}/overview

Parameters

domain*stringvendors, customers or materials.
statusstringreview, auto, accepted, split, conflict or all. conflict selects records with any field conflict. Default: all
qstringCase-insensitive substring over the golden name and the members. Up to 200 characters.
limitintegerPage size, 1 to 5000, capped at the configured page cap (500 by default). Default: 100
offsetintegerRecords to skip. Default: 0

Response fields

runobject | nullThe latest run: id, status (running, completed or failed), stats, error, started_at, finished_at.
totalintegerRecords matching the filter, before paging.
records[].keystringRecord key, a hash of the sorted member keys. Pass it to the record and decision routes.
records[].name / member_countstring / integerThe golden name and the number of members.
records[].statusstringauto, review, accepted or split.
records[].scorenumberLowest pair probability that holds the record together.
records[].conflict_levelstring | nullbad or warn.
records[].sources[] / conflict_fields[]arrayThe source rows (source and id) and the fields that conflict.

cURL: Records in review

curl "https://api.talonic.com/v1/master-records/vendors/overview?status=review&q=acme&limit=20" \
  -H "Authorization: Bearer $TALONIC_API_KEY"
GET/v1/master-records/{domain}/records/{key}

Response fields

members[]arrayThe source rows: source, id and values by field.
goldenobjectThe surviving value per field: { value, from } where from lists the sources that hold the value.
conflicts[]arrayFields whose non-empty values disagree: field, severity (bad or warn) and the values by source.
reasons[]arrayWhy the members were linked: field, outcome (match, close, differs or missing) and weight.
score / statusnumber / stringThe record's score and status (auto, review, accepted or split).
decisionstring | nullThe decision on file, accept or split, if any.
run_iduuidThe run the record belongs to.

Response: One golden record (abridged)

{
  "key": "3a7f9d1c5e2b8046a1d3c7f09b4e6a28d5c1f390",
  "domain": "vendors",
  "name": "Acme Industrial GmbH",
  "members": [
    { "source": "ERP-A", "id": "100234", "values": { "name": "ACME Industrial GmbH", "iban": "DE89370400440532013000" } },
    { "source": "ERP-B", "id": "V-8812", "values": { "name": "Acme Industrial", "iban": "DE02120300000000202051" } }
  ],
  "golden": { "iban": { "value": "DE89370400440532013000", "from": ["ERP-A"] } },
  "conflicts": [
    { "field": "iban", "severity": "bad", "values": [ { "source": "ERP-A", "value": "DE89370400440532013000" }, { "source": "ERP-B", "value": "DE02120300000000202051" } ] }
  ],
  "reasons": [ { "field": "name", "outcome": "close", "weight": 5.6 } ],
  "score": 0.87,
  "status": "review",
  "decision": null
}
Survivorship takes the most common normalized value per field, and the earliest source on a tie. Name, street and city spellings are not conflicts; a disagreement on iban or tax_id is bad, and any other differing field is warn. A bad conflict always sends the record to review.

Frequently asked questions

What is the record key?+
A hash of the record's sorted member keys, where a member key is the source label and the source id. It identifies the record within the latest run, and it changes when the membership changes, which is why a decision on a different set of rows never applies.
How are golden values chosen?+
For each field the most common normalized value wins, and the earliest source in the configured priority order breaks a tie. Each golden value lists the sources that hold it in from, so every value names where it came from.
Why does a record I know exists not appear?+
The overview lists only records with two or more members. A record from a single source is in the crosswalk and in the run statistics. Check the status filter too: the default is all, and a q filter matches the golden name and the members only.

Related

Master Records Overview
Run a Domain
Record Decisions
Crosswalk