Skip to main content

Entity Linking

Entity linking is the process that discovers relationships between documents automatically. After extraction, it reads the values of every link key field, normalizes them per category, and builds a bipartite graph of documents and entities. Documents that share entities end up connected, and connected clusters become cases. No language model is involved at this step: linking is deterministic string normalization and matching.

Normalization

The normalization step is critical for accurate linking. Values like "ACME Corp.", "Acme Corporation", and "acme corp" are all reduced to the same canonical form, acme corp, so they resolve to a single entity node. This prevents duplicate entities from fragmenting your cases and ensures documents that reference the same real-world party are correctly connected. Each link key category has its own rules, because a purchase order number and a company name vary in different ways.

  • Transaction values are uppercased, a leading type prefix (PO, INV, SO, REF, BOL, RC, CN, WO, QT, BK, TK, CL) and its separator are removed, spaces, hyphens, dots, and underscores are dropped, and leading zeros are stripped, so PO-000123, po 123, and 123 all match
  • Identity values are lowercased, repeated whitespace is collapsed, a trailing period is removed, and a long legal suffix is collapsed to its short form: Limited → ltd, Incorporated → inc, Corporation → corp, Gesellschaft mit beschränkter Haftung → gmbh, Aktiengesellschaft → ag, Société anonyme → sa, Société par actions simplifiée → sas, Public limited company → plc, Company → co
  • Reference values are trimmed and lowercased only, since project codes and cost centers are usually exact identifiers

Legal suffixes are collapsed, not removed, so "Acme Corp" and "Acme" remain two different entities. Values shorter than two characters, values that start with [, and structured (object) values are skipped, and a value repeated on the same document is indexed once. For edge cases where normalization is insufficient, such as a company using entirely different trading names, you can connect documents through the case operations (pinning documents, merging cases, confirming edges).

The document-entity graph

The resulting bipartite graph has two node types: documents and entities. An entity is one normalized value within one category, so the same string used as an Identity and as a Reference produces two separate entities. An edge connects a document to an entity whenever the document carries that value in a link key field, and the edge remembers which field it came from. Connected components in this graph become the foundation for case formation: a component with at least one Transaction or Reference entity becomes a case, and an Identity-only component becomes an entity group.

A typical flow: you upload a batch of invoices, contracts, and purchase orders. An invoice referencing "ACME Corp" and a contract referencing "Acme Corporation" both resolve to the identity entity acme corp, and both carry purchase order PO-4410, which normalizes to the transaction entity 4410. A purchase order document carrying the same number joins them, and because the component contains a transaction entity, the three documents form one case rather than a loose entity group.

  • Runs automatically after document extraction and resolution — no manual trigger required
  • Normalizes values per category: transaction prefixes and leading zeros, identity legal suffixes, reference lowercasing
  • Builds a bipartite graph: document nodes connected to entity nodes via link key edges
  • Connected components with a transaction or reference entity become cases; identity-only components become entity groups
  • Incremental: each new document is linked on its own, extending the existing graph rather than rebuilding it
  • Handles minor naming variations automatically; wildly inconsistent names may need manual link key tuning

Turning linking on and off

Entity linking is one of the per-workspace ingest stages in Settings → Automation, and it is on by default. When the stage is off, newly processed documents are not linked, while links that already exist stay in place. A linking backfill (POST /v1/linking/backfill, or Index all documents on the graph view) re-links every completed document regardless of that setting, which is the way to catch up after turning the stage back on or after changing link keys. Each document is re-indexed from scratch during a backfill, so stale links from an old configuration are replaced rather than accumulated.

List the entity links discovered for a document
curl -s https://api.talonic.com/v1/linking/documents/DOCUMENT_UUID/links \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Response:
# {
#   "data": [
#     {
#       "entity_id": "0c6f9a12-…",
#       "entity_value": "4410",
#       "link_key_category": "transaction",
#       "field_key": "purchase_order_number",
#       "document_count": 3
#     },
#     {
#       "entity_id": "7e21d4b8-…",
#       "entity_value": "acme corp",
#       "link_key_category": "identity",
#       "field_key": "supplier_name",
#       "document_count": 14
#     }
#   ]
# }
# document_count = how many documents in the organization carry this entity
Fetch the linking graph and the document-to-case map
# The entire document-entity graph for your workspace:
curl -s https://api.talonic.com/v1/linking/graph \
  -H "Authorization: Bearer $TALONIC_API_KEY"
# -> { "nodes": [ ... ], "edges": [ ... ], "cases": [ ... ],
#      "entity_groups": [ ... ], "stats": { ... } }

# Or just the neighbourhood around one document (depth defaults to 2):
curl -s "https://api.talonic.com/v1/linking/graph/documents/DOCUMENT_UUID?depth=2" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Map every linked document to its case or entity group:
curl -s https://api.talonic.com/v1/linking/document-case-map \
  -H "Authorization: Bearer $TALONIC_API_KEY"
# -> { "data": { "<document_id>": { "case_key": "8c1ca050535e3ea3",
#                                   "document_count": 3, "is_case": true } } }

Visibility rules apply to every linking read. If an access rule or an enforced Collection hides a document from the caller, asking for its links returns an empty list, exactly as for a document that does not exist, and hidden documents get no node in the graph. The document_count on an entity is an organization-wide tally and is not reduced for restricted viewers.

Entity linking is incremental: when new documents arrive, the linking engine extends the existing graph rather than rebuilding it from scratch, and existing cases grow as new connections are discovered. To force a full re-link after link key configuration changes, trigger POST /v1/linking/backfill.

Frequently asked questions

How does entity linking work?+
The linking engine reads link key values from each processed document, normalizes them per category, and builds a bipartite graph connecting documents to entities. Connected components with a transaction or reference entity become cases.
When does entity linking run?+
Entity linking runs automatically after a document is extracted and resolved, as long as the Entity linking ingest stage is on in Settings → Automation (the default). It processes link key values and builds connections without manual intervention.
What normalization does entity linking apply?+
Transaction values lose common prefixes such as PO or INV, separators, and leading zeros. Identity values are lowercased and long legal suffixes are collapsed to short forms such as ltd, inc, corp, or gmbh. Reference values are trimmed and lowercased.
What happens when new documents are added to an existing workspace?+
Entity linking is incremental. Each new document is linked on its own and extends the existing bipartite graph rather than triggering a rebuild. If it shares entity values with existing documents, it is connected to the relevant entity nodes and may join existing cases automatically.
How do I see which documents a specific document is linked to?+
Call GET /v1/linking/documents/{id}/links to list every entity the document is linked to, with the entity value, category, source field, and how many documents carry it. For the neighbouring documents themselves, call GET /v1/linking/graph/documents/{id}, or open the Document Graph view in the app.
Does turning off the Entity linking stage delete existing links?+
No. The toggle only stops new documents from being linked; links that already exist remain. Run a linking backfill to bring every completed document up to date once the stage is back on or your link keys change.

Related

Link Keys
Cases
Document Graph
Access Rules