Zonal Extraction (Template Zones)
What this page is — marking fixed areas on a document type's form, so that values sitting in the same place on every incoming copy are read automatically in the Capture Inbox.
What it is for — so key values on identically laid-out forms are read automatically, and duplicates are caught before they become records.
The problem it solves — every captured invoice or application otherwise has its values retyped by hand, and a resubmitted invoice is only caught if someone remembers it.
Route: /org/papers/designer/<type> → Zones tab, and /org/papers/capture ·
Permission: Create/edit/retire project types and template versions. (or Manage org-canonical types/templates (projects inherit). for org-wide types) to
mark zones; View this project's document types. to read them
1. What it is
A zone is a rectangle on a page of the form, stored as percentages of the page's width and height, with a target field. When a captured file is classified as that type, each active zone is read and its value is carried into the new document.
| Zonal extraction | Whole-document AI classification | Smart fields | |
|---|---|---|---|
| Reads | Only the marked rectangles | The whole file | Values already in Orbit |
| Needs a fixed layout | Yes | No | — |
| Cost on digital PDFs | None — reads the text layer | AI credits | None |
| Cost on scans | AI credits per zone | AI credits | — |
| Duplicate detection | Optional per zone | No | No |
Zones belong to the type, not a template version. They describe the incoming paper form, which does not change when you reword your own template.
2. Why you would use it
- Nobody retypes invoice numbers. At fifty supplier invoices a day, reading six values each is an hour of keying — and a source of transposed digits.
- Duplicates are caught at the door. A zone checked against existing records flags a resubmitted invoice before it becomes a second payable.
- Exact beats approximate. On digital PDFs the value comes from the text under the rectangle, with no model guessing, so no credits and no hallucinated numbers.
- Nothing breaks if it fails. An unreadable zone falls back to normal AI classification, so adding zones never makes capture worse.
3. Step by step
Marking zones
- Open the type in the Type Designer → Zones tab. With no sample loaded, the tab says "Upload a sample to mark zones".
- Click Upload a sample of this form (later Replace sample). It is rendered for drawing only — never stored and never attached to the type.
- Drag a rectangle over the spot where the value always sits. Use the page arrows for multi-page forms.
- In the zone card:
- Choose the Field — the type's fields are offered, or type a key.
- Add a Label.
- Optionally add a Cleanup pattern.
- Set the existing-records check.
- Click Save zones ("Zones saved").
- Pause a zone without deleting it with its badge. The tooltip reads "Zone is read on capture — click to pause it" or "Zone is paused — click to activate".
How a capture is read
4. Field reference
| Field | Required | Validation — exact messages |
|---|---|---|
| Field | Yes | zones[n]: field_key is required |
| Label | No | Free text, shown on the capture chips |
| Rectangle | Yes | zones[n]: the zone rectangle has no area; zones[n]: coordinates must stay within the page (0-100%) |
| Page | Yes | zones[n]: page_number must be >= 1 |
| Cleanup pattern (regex, optional) | No | zones[n]: extract pattern is not a valid regular expression. The first bracketed group is kept, otherwise the whole match. No match reports an error, never a wrong value |
| Existing-records check | No | Looks for documents of the same type whose field already holds this value. Off reads "Not checked against existing records" |
Sample upload rules
| Message | Cause |
|---|---|
| "the sample must be a PDF, PNG, JPG or TIFF file" | Wrong file type |
| "the sample file exceeds the 20MB limit" | Too large |
| "this file could not be opened — upload a PDF or image sample of the form" | Corrupt or password-protected |
In the Capture Inbox
| You see | Meaning |
|---|---|
| Green chip, e.g. Invoice number: INV-2026-041 | Read from the zone; hover shows text layer or vision |
| Amber chip with ⚠ | Already exists on another document of this type — possible duplicate |
| zones unreadable — AI text used | The zones could not be read; normal classification applies |
| Read zones for this type (Convert drawer) | Re-reads the file against a different type you picked |
Re-reading refuses with "document type "…" has no active zones — mark them in the Type Designer's Zones tab first" when that type has none.
5. Drawing zones that survive real paper
| Do | Why |
|---|---|
| Draw a little wider than the value | Scanned copies shift slightly. Scans get a 0.5% margin, but only that |
| Use a cleanup pattern for anything with a format | INV-([0-9]+) keeps 041 from Invoice No. INV-041 (copy) |
| Put one value in one zone | Two values in one rectangle come back joined |
| Turn on the existing-records check only for identifiers | Checking dates or amounts flags everything |
| Test with a scanned copy as well as a digital one | Scans take the vision path and cost credits |
Zones assume the same layout. A supplier who redesigns their invoice needs a new type or re-drawn zones.
6. Worked example
Gatiro's accounts team receives about 40 invoices a week from Northwind Supplies, always on the same template.
-
They create the type Supplier invoice — Northwind with fields
invoice_number,invoice_date,total_amountandpo_reference. -
On Zones they upload last month's invoice and draw four rectangles:
Label Field Pattern Check existing Invoice number invoice_number(NW-[0-9]{6})✓ Invoice date invoice_date— — Total total_amount([0-9,]+\.[0-9]{2})— PO po_reference(PO-[0-9]+)— -
Monday's emailed PDF arrives in the Capture Inbox. Classify suggests the Northwind type, and four green chips appear: NW-004417, 03/03/2026, 1,24,500.00, PO-8812. No credits are used, because the PDF has a text layer.
-
On Wednesday a scanned copy of the same invoice arrives. The number chip is amber: already on document "Invoice NW-004417". The clerk discards it instead of creating a duplicate payable.
-
On Friday a paper invoice is scanned. Its zones take the vision path, using a small credit charge per zone, and fill correctly.
7. The admin contract
| What must be configured | Otherwise |
|---|---|
| An active type with a published version and fields | Zone values have nowhere to land |
| The classifier suggesting this type | Zones are read only for the suggested type (use Read zones for this type otherwise) |
| Document OCR enabled, with AI credits | Scans fall back to ordinary classification; digital PDFs still read |
| A capture source feeding the inbox | Nothing to read — see capture inbox |
Zones can also be managed through the API (GET and PUT on /api/v1/ext/papers/types/<id>/zones) and
the assistant — see API and automation. Start with your highest-volume form.
8. Downstream
- Convert carries zone values into the new document's fields.
- Duplicate warnings never block. The decision stays with the person converting.
- The file uploaded as a sample is never stored. Only the captured files are.
9. Don't confuse this with…
| Capture inbox | Where files arrive and are classified. Zones enrich that step |
| Smart fields | Fill values from Orbit data, not from paper |
| Extract key terms | AI reading of a whole agreement's meaning, not fixed positions |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| No chips after Classify | The zone is paused, the classifier suggested another type, or the layout differs from the sample |
| The chip holds extra words | Tighten the rectangle, or add a cleanup pattern with a group |
| The zone reports an error instead of a value | The pattern did not match what was read |
| Scans never produce chips | Document OCR is disabled or out of credits |
| Every document is flagged as a duplicate | The check is on a non-unique field, such as a date |
| Save refused | See the zone messages in §4 — an empty field or a rectangle off the page |