Skip to main content

Data Products & Records

List the data products a document fill reads, inspect a product's columns and bound reference table, and read its rows with the documents each value came from.

Document Generation fills a template from the rows of a data product. Three read routes expose what a fill can use. The product list names the workspace's data products; one product returns its columns and its reference table; and the record route returns the rows themselves, each with its label, its column values, the documents of its group and the document each value came from. The record ids returned here are the ids a draft or a batch request names in record_ids.

The product list keeps each entry light: columns and previewColumns are empty there, and recordCount is the stored document count. GET /v1/doc-gen/products/{id} fills them. Its recordCount counts only the rows the key's minting user may read under Sources IAM, and reference describes the reference table the product's Spec binds to its rows: the table's id, name and columns, and the matchKey pairs (fieldKey, refColumn) that say how a row finds its reference row. reference is null when the Spec binds none.

Rows are filtered for the key's minting user too, so two keys in the same workspace can see different rows. q is a case-insensitive substring over the row label and every column value, total counts the rows matching q before limit is applied, and limit runs from 1 to 500 and defaults to 500. Each row's provenance maps a column to the document that supplied the value when the product knows it, which is the same origin information a generated document later carries.

GET/v1/doc-gen/products
GET/v1/doc-gen/products/{id}

Response fields

id, nameuuid, stringThe data product.
recordCountintegerRows the key's minting user may read under Sources IAM.
columns[]arrayPer column: field (the name sources refer to) and label.
previewColumnsstring[]Field names of the first text columns.
hrefstring | nullThe product's path in the web app.
referenceobject | nullThe bound reference table: id, name, columns[] and matchKey[] ({ fieldKey, refColumn }). Null when the Spec binds none.

Response: A product with a reference table (excerpt)

{
  "id": "7e2f9b14-3a6d-4c85-91f0-d4b8e5a2c763",
  "name": "Supply Contracts",
  "recordCount": 214,
  "columns": [
    { "field": "counterparty_name", "label": "Counterparty" },
    { "field": "contract_number", "label": "Contract number" }
  ],
  "previewColumns": ["counterparty_name", "contract_number"],
  "href": "/delivery/data-products/7e2f9b14-3a6d-4c85-91f0-d4b8e5a2c763",
  "reference": {
    "id": "c40a5e18-92d7-4b3f-8a61-5f1d7e9b0c24",
    "name": "Customer master",
    "columns": [{ "field": "contact_name", "label": "Contact" }],
    "matchKey": [{ "fieldKey": "contract_number", "refColumn": "contract_no" }]
  }
}
GET/v1/doc-gen/products/{id}/records

Query parameters

qstringCase-insensitive substring over the row label and every column value.
limitintegerMost rows to return, 1 to 500. Default: 500

Response fields

totalintegerRows matching q, before limit.
data[].id, labelstringThe record id (what record_ids takes) and its display label.
data[].documentNamestring | nullName of the row's anchor document.
data[].documents[]arrayEvery document of the row, the anchor first: id, name, anchor (true for the document the row stands for).
data[].valuesobjectColumn values by field name; a value is a string or null.
data[].provenanceobjectPer column: { documentId, documentName } of the document that supplied the value, when known.
data[].referencenullAlways null on this route; drafts and jobs read the reference row themselves.

cURL: Find a row by contract number

curl "https://api.talonic.com/v1/doc-gen/products/$PRODUCT_ID/records?q=C-2026-0417&limit=5" \
  -H "Authorization: Bearer $TALONIC_API_KEY"
A row that exists in the data product but is not readable by the key's minting user is invisible here and cannot be named in a draft or a batch: such a request is refused with 404, the same answer as for a row that is not in the product.

Frequently asked questions

Why are columns empty in the product list?+
The list is deliberately light. Both columns and previewColumns are empty there, and recordCount is the stored document count. GET /v1/doc-gen/products/{id} returns the columns, the reference table and a recordCount limited to rows the key's minting user may read.
Why is reference always null on the records route?+
The route returns rows without matching them to reference rows. Drafts and jobs read the matched reference row themselves when they fill a document, using the matchKey shown on the product.
Do two keys in one workspace see the same rows?+
Not necessarily. Rows are filtered by Sources IAM as the key's minting user, so keys created by different people can return different rows and different recordCount values.

Related

Document Generation Overview
Field Sheet Proposals
Generate Documents
List Data Products