Skip to main content

Link Keys

List all discovered link keys with classification category and frequency. Link keys are the field-level entity identifiers that connect related documents.

The linking graph connects documents through shared entity values — an invoice and a contract sharing the same customer ID are linked. The API exposes the bipartite document-entity graph: link keys (field-level entity identifiers), document-level links, the full graph, document-centric subgraphs, classification (identity, transaction, reference), backfill, and document-to-case mapping.

Link keys are the fields that the linking engine uses to discover connections between documents. Each link key has a classification category — identity (e.g. vendor ID, customer number), transaction (e.g. invoice number, PO number), or reference (e.g. contract reference). Use this endpoint to inspect which fields are currently recognized as link keys and how frequently they appear across your documents.

Link keys are discovered automatically during extraction. If a field is not yet classified, use the Classify endpoint to trigger AI-based classification on ambiguous fields.
GET/v1/linking/link-keys

Request

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

Response

Response fields

dataarrayArray of link key objects.
data[].idstringField registry UUID.
data[].canonical_namestringCanonical field name used as the link key.
data[].display_namestring | nullHuman-readable display name for the field.
data[].data_typestringData type of the field (e.g. string, number, date).
data[].link_key_categorystring | nullLink key category: identity, transaction, or reference.
data[].occurrence_countintegerNumber of documents where this field has been extracted.

Response

{
  "data": [
    {
      "id": "freg_uuid_1",
      "canonical_name": "customer_id",
      "display_name": "Customer ID",
      "data_type": "string",
      "link_key_category": "identity",
      "occurrence_count": 142
    },
    {
      "id": "freg_uuid_2",
      "canonical_name": "invoice_number",
      "display_name": "Invoice Number",
      "data_type": "string",
      "link_key_category": "transaction",
      "occurrence_count": 87
    }
  ]
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

What are link keys in Talonic?+
Link keys are field-level entity identifiers (e.g. customer_id, invoice_number) used to connect documents that share the same value.
What is the difference between identity, transaction, and reference link keys?+
Identity keys represent stable entity identifiers (e.g. vendor ID, tax number). Transaction keys are document-specific identifiers (e.g. invoice number, PO number). Reference keys are cross-references between documents (e.g. contract reference cited in an invoice).
How are link keys discovered?+
Link keys are discovered automatically during document extraction. Fields are classified using rule-based heuristics first, then an LLM call for ambiguous cases. You can also trigger classification manually via the Classify endpoint.

Related

Classify
List Cases