Catalog Lookup Rule

The Catalog Lookup preset matches a document's extracted fields against a reference catalog and validates (or enriches) them from the matched record. It is the preferred, no-code way to answer questions like "is this a known vendor?", "does this invoice match an approved purchase order?", or "fill in the vendor's tax ID from our master list". It is a document-level validation rule that stays fully editable in the visual Rule Editor.

What a catalog is

A catalog is a tenant-wide reference table: an easy-to-edit copy of an external list or database. Each record has typed columns. Common examples:

• a vendor list (each record: name, address, tax ID, IBAN),
• a purchase-order list (PO number, line item, quantity, price),
• a budget/cost-code list.

You manage catalogs and their records from the Catalog area of the app. A single catalog can be reused by many projects and many rules.

When to use it

Use a catalog lookup instead of a script when you want to check extracted data against a maintained list and, optionally, pull reference values back into the document. Reach for a custom rule only when the match needs logic the preset cannot express (custom scoring, conditional lookups, combining a lookup with other checks).

Creating the rule

From the document's rules, add a Catalog Lookup rule and configure:

1. Catalog: which reference table to match against.
2. Field to column mappings: one or more pairs, each tying an extracted field to a catalog column, with a comparison mode (below).
3. Confidence threshold: the minimum match score to accept a unique match (default 0.8).
4. Reviewer permissions: what reviewers may do with the catalog from the Viewer.

You can also ask the Copilot to build it for you: describe the match in plain language ("match the supplier against the Vendors catalog on tax ID, and fill in the address") and it configures the mapping and saves the rule to your draft.

Comparison modes

Each field-to-column pair uses one mode:

Mode	Behavior
Exact	The field value must equal the column value (after normalization) to match. Use for identifiers: PO numbers, tax IDs, SKUs.
Fuzzy	Approximate string match (handles spelling and spacing differences). Use for names and addresses.
Filter	A hard exact constraint that narrows which catalog records are even eligible before the other pairs match. Use for "match only within this scope".
Get from catalog	The field is not used to search. Once a record is matched by the other pairs, this field's value is copied from the catalog column. Use to enrich the document (fill the tax ID and address from the matched vendor).

Exact vs Filter

Exact and Filter both require an equal value, but they differ in intent:

• Exact is a field you are verifying. If it doesn't match, the record still counts as a near miss and the rule reports a mismatch on that field.
• Filter is a boundary you are matching inside of. Records whose filter column differs are removed from consideration entirely. If the document's filter value is empty, the lookup fails as "no match" (there is nothing to scope to). Filter also scopes the reviewer's manual lookup and add-record to that value, so a reviewer searching by hand only sees records within the same boundary.

A typical Filter use is "suppliers only for this receiving company", or "line items only under this purchase order".

Empty-value handling

Two independent switches per pair (they do not apply to Filter pairs, which require non-empty values on both sides):

• Allow empty value in document: if the document field is empty, exclude it from the search (the match proceeds on the other pairs). If a record is then found, the empty field is populated from the catalog.
• Allow empty value in catalog: treat catalog records whose column is empty as matching regardless of the document value (an empty column does not block the match).

Per-row (per line item) lookups

If any mapping targets a repeating-group column (a table / line-item column), the rule automatically runs once per row of that table. No separate setting is required: the rule detects the per-row scope from the mapped columns.

Mappings in the same rule that point at non-table fields become shared constraints applied to every row. This is exactly what you want for matching invoice line items against a purchase-order catalog: the PO number is a single document-level value shared across all lines, while each line's item code is matched per row.

Example: match each invoice line item to the PO Items catalog:

Document field	Catalog column	Mode
PO Number	po_number	Filter
Line Items → Item Code	item_code	Exact
Line Items → Description	description	Get from catalog
Line Items → Unit Price	unit_price	Get from catalog

Each row is matched against the catalog within the document's PO number. On a match, the description and unit price are filled into that row's cells. An empty table (no rows) runs no lookups, so it raises no errors.

What reviewers see

In the Transaction Viewer, each lookup produces one of:

• Unique match: the rule passes. Fields mapped as get from catalog are populated, and the engaged fields are auto-confirmed (if "confirm fields on success" is on).
• No match: the rule raises an error. The failing field (or, for a per-row rule, the failing row's cells) is highlighted red, and a Look up in catalog action lets the reviewer search the catalog by hand and apply a record.
• Ambiguous: more than one record matched above the threshold; the reviewer picks the correct one.

When a reviewer applies a record by hand, the matched values populate the correct field (or the correct row's cells for a per-row rule), the rule re-runs immediately, and the error clears.

Reviewer permissions

These control what a reviewer may do with the catalog from the Viewer:

Permission	Default	Effect
Manual lookup	On	Search the catalog by hand and apply a record.
Add records	Off	Create a new catalog record from the Viewer.
Edit records	Off	Edit an existing record.
Delete records	Off	Delete a record.

Turn add / edit / delete on only when you want reviewers to curate catalog data during review. A Filter mapping also scopes manual lookup and add-record to the filter's value.

Updating the catalog automatically

Reviewer permissions cover manual curation. If you want the workflow itself to keep the catalog up to date (for example, register a vendor the first time a document arrives from it), add a Data Transform step. Its script can look records up and queue catalog.add_record / catalog.update_record / catalog.delete_record writes, which are applied when the script finishes successfully. A common pattern pairs the two: the catalog lookup rule flags documents whose vendor is unknown, and a Data Transform step later in the workflow registers the missing vendor.

Tips

• Put identifiers on Exact, names on Fuzzy. IDs, PO numbers, and tax IDs should match exactly; vendor names and addresses vary, so use fuzzy.
• Use Filter for a scope, not a check. If a value defines "which records are even eligible" (receiving company, PO number), make it a Filter, not an Exact.
• Enrich with Get from catalog. Any field you want filled from the matched record (address, tax ID, unit price) goes on get from catalog, not on the search.
• Verify on a sample. After creating or editing the rule, re-validate a sample transaction and check the Viewer before publishing.

See also: Business Rules overview and Custom (Script) Rules for logic-heavy matches the preset cannot express.