Templates & Fields

A Template is a saved, reusable list of Fields you want extracted from a document — one field per output column. Pass a Template's id to Start processing a batch instead of re-listing your fields on every call. You can also build a Template from a built-in preset, or skip Templates entirely and pass ad-hoc fields directly to process for a one-off run.

List templates

Returns your saved templates, each with its full, ordered field list embedded.

GET /api/v1/templates

Parameters

Name	Location	Type	Description
`limit`	query, optional	integer	1–100. Default 50.
`page_token`	query, optional	string	Opaque cursor from a previous response's `next_page_token`. See Pagination.

Possible errors

missing_api_key / invalid_api_key / plan_required — see Error Handling.
invalid_parameter — bad limit or page_token.

Create a template

Two ways to create a template in one endpoint: from scratch (optionally cloning another template's fields via base_template_id), or from a built-in preset via preset_id. Accounts are capped at 30 templates — delete an existing one before creating another once you hit the limit.

POST /api/v1/templates

Parameters

Name	Location	Type	Description
`name`	body (JSON)	string	Required unless `preset_id` is given (in which case it falls back to the preset's own name, disambiguated with a timestamp suffix if you already have a template with that name).
`preset_id`	body (JSON)	string, optional	Build the template (and its fields) from a built-in preset — see List presets for valid IDs.
`base_template_id`	body (JSON)	integer, optional	Only used when `preset_id` is not given — clones this existing template's fields into the new one.

Possible errors

missing_api_key / invalid_api_key / plan_required — see Error Handling.
missing_parameter (param: "name") — no name and no preset_id.
invalid_parameter (param: "name") — a template with this name already exists (non-preset creation path only).
invalid_parameter (param: "preset_id") — unknown preset ID.
template_limit_reached — already at the 30-template cap for this account.
internal_error

Update template settings

Sets a template's global format requirement (applied on top of every field's own) and its Multi-Page Merge configuration — whether multiple uploaded pages that belong to the same logical record (a multi-page lease, a stapled receipt bundle) should fold into a single output row instead of staying one row per page. Once enabled here, merge is applied automatically wherever this template is used for both processing and results — see ?merge=true on Get batch results and Export a batch (which always applies it, no opt-in needed there). Every field in the request body below is optional; only the keys you send get updated, everything else is left as-is (there's no separate draft/preview state to confirm — this call takes effect immediately, same as the web app's Template Settings dialog).

PUT /api/v1/templates/{id}/settings

Parameters

Name	Location	Type	Description
`id`	path	integer	The template to update.
`global_format_requirement`	body (JSON), optional	string	Extra instructions applied on top of every field's own `format_requirement`.
`merge_enabled`	body (JSON), optional	boolean	Turns Multi-Page Merge on/off. Every `merge_*` field below is meaningless while this is `false`.
`merge_mode`	body (JSON), optional	string or null	`"sequential"` (new record when a Data Column's value changes), `"key_match"` (group by matching Data Column value regardless of upload order), or `"fixed_count"` (group every N uploads).
`merge_field_name`	body (JSON), optional	string or null	The Data Column (field name) used by `sequential`'s value-based triggers and by `key_match`'s grouping key.
`merge_trigger_type`	body (JSON), optional	string or null	Only for `sequential`: `"value_change"`, `"blank"`, `"has_value"`, or `"equals_value"`.
`merge_trigger_value`	body (JSON), optional	string or null	Only for `merge_trigger_type: "equals_value"` — the text or regex to match.
`merge_fixed_count`	body (JSON), optional	integer or null	Only for `merge_mode: "fixed_count"` — group size, minimum 1.
`merge_conflict_policy`	body (JSON), optional	string or null	When grouped pages disagree on a field's value: `"split"` (one output row per page instead of merging), `"first"`, `"last"`, or `"concat"` (default).
`merge_conflict_separator`	body (JSON), optional	string or null	Used when `merge_conflict_policy: "concat"`, max 20 characters. `null` falls back to the default `" / "`; `""` is a deliberate "no separator" choice and is stored as-is.
`merge_skip_preview`	body (JSON), optional	boolean	Web-app-only concern (gates the export-preview confirmation screen) — has no effect on API behavior, since the API has no interactive preview step to skip. Settable here purely so a template's full config round-trips through this one endpoint.

Possible errors

missing_api_key / invalid_api_key / plan_required — see Error Handling.
template_not_found
invalid_parameter — bad merge_mode / merge_trigger_type / merge_fixed_count / merge_conflict_policy / merge_conflict_separator.
internal_error

Delete a template

Deletes a template and all of its fields (cascades — no separate cleanup call needed). Does not affect documents that already used this template in a past process call; their already-extracted results are untouched.

DELETE /api/v1/templates/{id}

Parameters

Name	Location	Type	Description
`id`	path	integer	The template to delete.

Possible errors

missing_api_key / invalid_api_key / plan_required — see Error Handling.
template_not_found
internal_error

List presets

Built-in field lists for common document types (invoices, receipts, bank statements, and more) — pass a preset's id as preset_id to Create a template to get a working template without hand-listing fields yourself. Presets are static configuration, not database rows — there's no way to create, edit, or delete one through the API.

GET /api/v1/presets

Parameters

Name	Location	Type	Description
`category`	query, optional	string	Filter to one category (e.g. `"Finance & Accounting"`). Omit to list all categories.
`limit`	query, optional	integer	1–100. Default 50.
`page_token`	query, optional	string	Opaque cursor from a previous response's `next_page_token`.

Possible errors

missing_api_key / invalid_api_key / plan_required — see Error Handling.
invalid_parameter — bad limit or page_token.

List and create fields

fields is the v1-public name for what the product UI calls "match rules" — one field per output column, in the order extraction will emit them. GET returns every field on the template, already sorted by sort_order. POST adds a new field to the end.

GET POST /api/v1/templates/{id}/fields

Parameters

Name	Location	Type	Description
`id`	path	integer	The template these fields belong to.
`name`	body (JSON), POST only	string	Required. Must be unique within this template — see errors below.
`format_requirement`	body (JSON), POST only	string, optional	Free-text hint about the expected value format (e.g. `"YYYY-MM-DD"`, `"Number"`).

Possible errors

missing_api_key / invalid_api_key / plan_required — see Error Handling.
template_not_found
missing_parameter (param: "name") — POST only.
duplicate_field_name — a field with this name already exists on this template.
internal_error

Update and delete a field

PUT renames a field (and replaces its format_requirement) — it's a full replace, not a partial patch, so include both values even if only one changed. DELETE removes it.

PUT DELETE /api/v1/templates/{id}/fields/{field_id}

Parameters

Name	Location	Type	Description
`id`	path	integer	The template this field belongs to.
`field_id`	path	integer	The field to update or delete.
`name`	body (JSON), PUT only	string	Required. New name.
`format_requirement`	body (JSON), PUT only	string, optional	New format hint — omit and it's cleared to an empty string, not left unchanged.

Possible errors

missing_api_key / invalid_api_key / plan_required — see Error Handling.
template_not_found — the template doesn't exist/isn't yours, or (with a message noting this) the field_id isn't on this template.
missing_parameter (param: "name") — PUT only.
duplicate_field_name — PUT only, renaming to a name another field on this template already has.
internal_error

Reorder fields

Explicitly sets field order, which determines output column order in line_items and in Excel/Word exports. IDs in the list that don't belong to this template are silently ignored rather than rejecting the whole request.

PATCH /api/v1/templates/{id}/fields/order

Parameters

Name	Location	Type	Description
`id`	path	integer	The template to reorder.
`field_ids`	body (JSON)	array of integers	Every field ID on this template, in the order you want them to appear. Required.

Possible errors

missing_api_key / invalid_api_key / plan_required — see Error Handling.
template_not_found
invalid_parameter (param: "field_ids") — not a list of integers.
internal_error

Get Started

Guides

API Reference

More

Templates & Fields

List templates

Parameters

Possible errors

Create a template

Parameters

Possible errors

Update template settings

Parameters

Possible errors

Delete a template

Parameters

Possible errors

List presets

Parameters

Possible errors

List and create fields

Parameters

Possible errors

Update and delete a field

Parameters

Possible errors

Reorder fields

Parameters

Possible errors