Link Keys

Link keys are field registry fields whose values connect related documents. When two documents share a link key value, such as the same purchase order number or company name, the linking engine connects them and groups them into cases for holistic review. Link keys fall into three categories: Identity (names), Transaction (reference numbers), and Reference (shared IDs like project codes). Only fields flagged as link keys take part in the document-entity graph, so this flag decides which values can ever join two documents.

Link key categories

• Identity: company names, supplier names, person names — connects documents referencing the same party
• Transaction: contract numbers, PO numbers, invoice numbers — connects documents in the same transaction chain
• Reference: project codes, cost centers, shared IDs — connects documents under the same organizational grouping

The category matters beyond labelling. Each category has its own value normalization (see Entity Linking), and only Transaction and Reference entities can turn a group of connected documents into a case. Documents that are connected through Identity entities alone form an entity group instead: sharing a supplier name is a useful signal, but it does not prove two documents belong to the same transaction.

How classification works

Most link keys are auto-classified by name patterns: the classification engine applies rule-based heuristics first, so field names like supplier_name or invoice_number are recognized instantly. When heuristics are inconclusive, an AI classifier examines the field's name, data type, occurrence count, and up to three sample values to determine the correct category. This two-stage approach keeps classification fast for the common case while handling ambiguous fields gracefully.

• Never by rule: names containing date, amount, price, rate, percent, currency, address, street, city, country, zip, postal, phone, fax, email, tax, vat, iban, bank, or signatory
• Identity by rule: the name contains _name together with a party word such as company, supplier, vendor, customer, client, tenant, landlord, contractor, counterparty, carrier, buyer, seller, payee, or payer
• Transaction by rule: the name contains _number, _no, _id, _code, _reference, or _ref, or words such as invoice, contract, order, booking, ticket, claim, tracking, shipment, or waybill
• Reference by rule: the name contains project, cost_center, site, location_code, department, meter_point, property_ref, commodity, trailer, or container

Fields the rules leave open go to the AI classifier, which is told to be conservative: a good link key connects a subset of documents (roughly 2 to 20), and postal codes, addresses, phone numbers, tax and bank identifiers, dates, amounts, free text, signatories, and contact persons are always rejected. A verdict below 0.7 confidence is ignored; a verdict between 0.7 and 0.9 is applied but marked as auto-suggested so you can spot it in review; 0.9 or above is applied outright. Whenever at least one new link key is classified, a linking backfill starts automatically.

Classification runs automatically as documents arrive and batches complete, and in that mode it also considers Candidate-maturity fields with at least one occurrence, so a brand-new workspace gets link keys from its first documents. A manual POST /v1/linking/classify call is narrower: it looks at up to 100 fields of Core or Proven maturity that are not yet link keys, highest occurrence count first.

High-frequency entity exclusion is an important safeguard. If an entity value appears in more than 30% of the linked documents, for example a generic department name like "Operations", it is excluded from case formation. An Identity value present in more than half of the linked documents is treated as the owner of the document set (typically your own organization name) and excluded for the same reason. Without this filter, a single high-frequency value would pull most documents into one enormous case. Excluded entities still appear in the graph, flagged with the reason, so you can see why they did not connect anything.

curl -s https://api.talonic.com/v1/linking/link-keys \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Response (sorted by category, then name):
# {
#   "data": [
#     {
#       "id": "4b7e2c1a-…",
#       "canonical_name": "supplier_name",
#       "display_name": "Supplier Name",
#       "data_type": "string",
#       "link_key_category": "identity",
#       "occurrence_count": 412
#     },
#     {
#       "id": "a90d5f33-…",
#       "canonical_name": "purchase_order_number",
#       "display_name": "Purchase Order Number",
#       "data_type": "string",
#       "link_key_category": "transaction",
#       "occurrence_count": 268
#     }
#   ]
# }

# Run rule + AI classification on fields that are not yet link keys:
curl -X POST https://api.talonic.com/v1/linking/classify \
  -H "Authorization: Bearer $TALONIC_API_KEY"
# -> { "classified": 4, "backfillTriggered": true }

# After changing link key configuration, re-link every completed document.
# The call returns when the re-index has finished (or at once if one is
# already running for your organization):
curl -X POST https://api.talonic.com/v1/linking/backfill \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Poll progress from another client while it runs:
curl -s https://api.talonic.com/v1/linking/backfill/progress \
  -H "Authorization: Bearer $TALONIC_API_KEY"
# -> { "total": 1840, "processed": 620, "running": true,
#      "entities_created": 311, "links_created": 2207 }

Reviewing and overriding classifications

Link key classification is the foundation of the linking and case formation system. If too many fields are classified as link keys, cases become over-connected with hundreds of documents grouped together. If too few are classified, documents that should be related end up as isolated singletons. Review your link key assignments in the Field Registry after the first batch of documents, and change a field's category there when the automatic classification does not fit your domain. Turning a field on with a category starts a background backfill so existing documents are re-linked; turning it off clears its category.

Two edge cases are worth knowing. Automatic classification only ever looks at fields that are currently not link keys, so a field you switch off can be proposed again by a later run if its name matches the rules; renaming it in the registry or reviewing after each large ingest keeps that in check. And changing link keys is a model-configuration action: in a self-service organization an Admin can make the change, while in a managed organization Talonic configures it. Consistent names like invoice_number and supplier_name maximize the hit rate of the automatic classifier and minimize the need for manual overrides.