Skip to main content

List Record Set Fields

List the field definitions of a record set: field keys, display names, data types, position order, and required or hidden flags that define the columns.

List the field definitions of a record set. Fields define the columns available in the set: each field has a field_key (the column name used to key cell values), a data_type, an optional display_name, a position that fixes the column order, and is_required and is_hidden flags. Use this endpoint to learn the shape of the data before fetching records.

Field definitions are derived from the schema used during extraction or the policy used during resolution, so different record sets can carry different columns even when they originate from the same documents. The response is ordered by position ascending, which is the same order used for display and export. Fetching the field list first also lets you build dynamic table UIs that adapt to whatever columns a set defines.

display_name is always populated: when the run that wrote the set stored no explicit display name, the API returns a humanized form of the field_key (for example invoice_number becomes Invoice Number), so you can bind column headers to it directly without your own fallback logic. field_key remains the stable machine identity — renames of the display name never change how cell values are keyed.

data_type names the typed storage a cell value uses — string, number, date, boolean, plus object and array for JSON-shaped values — so you can declare typed table columns without sniffing values at read time. is_required marks columns the source schema declares mandatory, and is_hidden marks helper columns excluded from default display; skip hidden columns in end-user UIs but keep reading them when you need the full audit picture.

GET/v1/record-sets/{id}/fields

Path parameters

id*uuidRecord set UUID. Must belong to your organization.

Response

Response fields

dataarrayArray of field definition objects, ordered by position.
data[].idstringField definition UUID.
data[].field_keystringField key (column name). Cell values in records are keyed by this.
data[].display_namestringHuman-readable display name. Always populated — a humanized field_key is returned when no explicit name is stored.
data[].data_typestringValue type of the column: string, number, date, boolean, object, or array.
data[].positionintegerColumn order position (ascending).
data[].is_requiredbooleanWhether the field is marked required in the set.
data[].is_hiddenbooleanWhether the field is hidden from default display.
links.selfstringURL of this field list.
links.record_setstringURL of the parent record set.

curl

curl -s https://api.talonic.com/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/fields \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

{
  "data": [
    { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "field_key": "invoice_number", "display_name": "Invoice Number", "data_type": "string", "position": 0, "is_required": true, "is_hidden": false },
    { "id": "f2b3c4d5-e6f7-8901-bcde-f23456789012", "field_key": "vendor_name", "display_name": "Vendor Name", "data_type": "string", "position": 1, "is_required": false, "is_hidden": false },
    { "id": "f3c4d5e6-f7a8-9012-cdef-345678901234", "field_key": "total_amount", "display_name": "Total Amount", "data_type": "number", "position": 2, "is_required": false, "is_hidden": false },
    { "id": "f4d5e6f7-a8b9-0123-def0-456789012345", "field_key": "invoice_date", "display_name": "Invoice Date", "data_type": "date", "position": 3, "is_required": false, "is_hidden": false }
  ],
  "links": {
    "self": "/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/fields",
    "record_set": "/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Build a CSV header from the visible columns

curl -s https://api.talonic.com/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/fields \
  -H "Authorization: Bearer tlnc_your_api_key" \
  | jq -r '[.data[] | select(.is_hidden | not) | .display_name] | @csv'
The field_key values returned here are the keys of the values map on each record. Fetch fields once, then use them to interpret every page of the records endpoint.

Errors

Error responses

400VALIDATION_ERRORThe id path parameter is not a valid UUID.
401unauthorizedMissing or invalid API key.
404not_foundRecord set not found or does not belong to your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

Where do the field definitions come from?+
Field definitions are derived from the user schema (for structured layer sets) or the data policy output contract (for resolved layer sets). They represent the declared columns that the extraction or resolution pipeline was configured to produce.
Can different record sets have different fields?+
Yes. Each record set has its own independent field definitions. A structured record set may have different fields than a resolved record set, even if they originate from the same documents, because the resolution policy may add, rename, or transform fields.
How are fields ordered?+
Fields are returned sorted by their `position` value in ascending order. This is the stable column order used for display and export, so you can render columns in the order they arrive.
What values can data_type take?+
string, number, date, boolean, object, or array. The type tells you which typed slot the value plane stores the cell value in, so a number column always yields a JSON number and a date column an ISO date string — no client-side value sniffing needed.
Is display_name ever null?+
No. When the set has no stored display name for a column, the API returns a humanized form of the field_key instead, so display_name is always a non-empty string you can bind headers to. Use field_key, not display_name, as your stable machine identifier.

Related

Get Record Set
List Record Set Records
List Extractions