Skip to main content

Document Links

Get all entity links for one document: entity values, field keys, link key categories (identity, transaction, reference), and shared-document counts per link.

Retrieve all entity links discovered for a specific document. Each link represents a shared field value — such as a customer ID or PO number — that connects this document to others in the workspace. Use this endpoint to understand how a document relates to the rest of your corpus.

Call this endpoint when building a document detail view or when you need to trace the relationships of a single document before exploring the broader graph. Pass the document UUID as a path parameter — the endpoint returns all entity links regardless of link key category.

Each entry in the response includes the entity_value (the raw shared value), the field_key (which field it was extracted from), and the link_key_category (identity, transaction, or reference). Documents with no extracted field values matching other documents return an empty data array.

Use this alongside the Full Graph subgraph endpoint to progressively explore the linking graph. Start here for a flat list of connections, then call the subgraph endpoint with depth=2 to expand outward from the document and discover second-degree relationships.

The document_count field on each entity indicates how many documents share that value. A high count on an identity entity (e.g. a vendor ID appearing in 50+ documents) is expected, while a high count on a transaction entity may indicate a data quality issue.
GET/v1/linking/documents/{id}/links

Request

curl https://api.talonic.com/v1/linking/documents/DOCUMENT_UUID/links \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response

Response fields

dataarrayArray of entity link objects.
data[].entity_idstringEntity UUID.
data[].entity_valuestringRaw entity value shared across documents.
data[].link_key_categorystring | nullLink key category: identity, transaction, or reference.
data[].field_keystringField name where this entity value was extracted.
data[].document_countintegerNumber of documents sharing this entity value.

Response

{
  "data": [
    {
      "entity_id": "ent_uuid_1",
      "entity_value": "ACME-001",
      "link_key_category": "identity",
      "field_key": "vendor_id",
      "document_count": 5
    },
    {
      "entity_id": "ent_uuid_2",
      "entity_value": "PO-2024-001",
      "link_key_category": "transaction",
      "field_key": "po_number",
      "document_count": 2
    }
  ]
}

Errors

Error responses

400validation_errorInvalid document ID format. Must be a UUID.
401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

What does document_count represent?+
The number of documents in your workspace that share the same entity value for that field. For example, if three invoices reference vendor ID "ACME-001", the document_count is 3.
Can a document have zero links?+
Yes. Documents that have no extracted field values matching other documents will return an empty data array. These appear as unlinked in the graph.
How is this different from the document subgraph endpoint?+
This endpoint returns a flat list of the entity values a document shares with others. The subgraph endpoint (GET /v1/linking/graph/documents/:id) returns nodes and edges for graph traversal, expanding outward to the linked documents themselves.

Related

Full Graph
Link Keys
Document-Case Map