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.

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.
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