Transformation rules look values up in the supporting files linked to them. By default that lookup matches on any part of the text, which is usually the desired behavior but is sometimes wrong: a shorter code in a supporting file can match inside a longer code printed on the document. A matching instruction changes how a lookup compares text. You write it as a plain sentence in your custom instructions, with no rule numbers and no special syntax, and it is applied the same way to every document from then on.

How It Works

Why Matching Sometimes Needs Changing

A rule that says if the description contains a code from the supporting file, fill in the Article ID matches on any part of the text. Where codes in a supporting file are contained inside one another, that produces wrong fills:


The line item printed	`26103110AC10315580`
The supporting file contained	no such code, but a separate row `0315`
So the rule matched	`0315`, because those four characters appear inside the longer code
And the Article ID became	`0315`

The same behavior turns a printed W8880T into W888. Master files commonly contain codes that sit inside other codes in the same file, so this is a structural risk rather than an unlucky one. Asking for whole-word matching removes it.

Every Matching Instruction Has Two Parts

A matching instruction must say which rules it is addressed to, and then describe what should change. The second part alone has no effect.

Part One: Say You Are Addressing the Rules

An instruction only changes matching behavior if it states that it is about your transformation rules or about a lookup in a supporting file. One of these phrases, anywhere in the instruction, is enough:

Say one of these	And it means
"for transformations", "when evaluating transformation rules"	every transformation rule on the document
"from the supporting file", "from the uploads", "the master file", "the attached CSV"	every rule that consults a file, and no others
the name of your file as you sent it	the rules that use that file

This requirement is deliberate, and it is the most important safety property of the feature. Custom instructions are full of sentences that describe how to read a document, and reading is described using the same vocabulary as matching. An instruction such as only use the value whose label, ignoring capital letters, is exactly Pagero ID is telling Docupath where to look on the page, even though it contains the words "exactly" and "ignoring capital letters". If a sentence like that quietly became a matching rule, it would change how every rule in your account compares text.

So each sentence is classified before any of its wording is interpreted, and the deciding question is whether the sentence says where on the page a value comes from. If it does, it is a reading instruction and it is left completely alone.

If you write an instruction that clearly asks for a matching change but does not say which rules it means, it is not silently ignored. It is listed on the document under "This looks like a matching instruction, and it did nothing", together with the wording that would make it work.

Part Two: Narrow It to Specific Rules

Once the instruction says it is addressing the rules, you can point it at a subset, in your own words:

You add	Docupath understands
"when filling the article id"	the rule that writes that field
"when looking at the article description"	the rule that reads that field
"when using the article master file"	the rules that consult that file

Narrowing matters more than it appears to. A document can carry a handful of rules that use a supporting file alongside many more that match plain text, so "from the supporting file" changes only the former. Similarly, "for transformations, match whole words" governs every condition on the document, whereas "when evaluating transformations, match the whole word for Article ID" governs only the conditions on that field. Narrower is safer, so name the field wherever you can.

Part Three: Describe What Should Change

To make matching stricter:

You write	What happens
"match the full word only", "no partial matches", "the code must stand on its own"	`AB` stops matching `ABC`
"the case must match exactly"	upper and lower case must agree
"it must be an exact match, not a contains"	the field must equal the value

To make matching more forgiving:

You write	What happens
"ignore punctuation", "dots and dashes should not matter"	`A.B.C.` matches `ABC`
"ignore accents"	`Müller` matches `Muller`
"allow small typos"	one or two characters of difference are tolerated
"equals doesn't mean exact, it just has to be in there"	an equals rule behaves like contains
"look for it anywhere on the page"	the whole document is searched, not just that one field

These can be combined. "For transformations, only match full words and ignore any special characters" is understood as both changes.

Matching Is Set Per Condition, Not Per Rule

A rule often checks several conditions before it fills a value. A ship-to rule might require the street, the second street line, the name and the second name line all to match. You can change one of those conditions and leave the others exactly as they are:

"For transformations: when looking at street 1, allow small typos. When looking at name 1, search the whole document."

Street 1   ->  tolerates a one-character OCR slip
Street 2   ->  unchanged, still exact
Name       ->  searched across the whole document
Name 2     ->  unchanged, still exact

You only need to state the reference once. The reference at the front of the instruction covers every condition you go on to list, including across separate sentences. Conditions you do not mention keep their existing precision.

Safety Rules Applied to Forgiving Matches

Making matching stricter is always safe, because it can only remove a wrong match. Strict changes apply immediately, and they apply to rejection rules too. That resolves a real problem: a rejection rule that blocks documents where the supplier name contains BLOCKED also blocks a supplier called UNBLOCKED Ltd. Whole-word matching stops that.

Making matching more forgiving can create a match that was not there, so forgiving requests are held to four rules:

It can only fill a blank. A forgiving match never overwrites a value produced by an ordinary rule, and never overwrites something already on the document. It can add, never change.
If two forgiving matches disagree, nothing is written. Three hospitals named Polo HP, Polo HG and Polo HUC are one character apart and carry different codes. Guessing between them would be worse than leaving the field empty, so the field is left empty and the reason is reported.
There has to be something substantial to match on. At least three letters or digits are required on both sides. A rule that looks for a comma would otherwise match every document once punctuation is ignored.
Never on rejection rules. Rejecting a document must never rest on an approximate match.

Matching Instructions Are Not Sent to the Extraction AI

Two separate things happen to every document. An AI reads it and pulls out the fields. Then the extracted values are matched against your supporting files and your rules are applied. A matching instruction is addressed to the second of these.

The reader has no rules and no supporting file, so a matching instruction is of no use to it, and passing it along is not harmless: the reader may try to obey it and damage what it reads, and every extra sentence competes for attention with the instructions that genuinely are for it. Matching instructions are therefore kept away from the reader entirely, in the same way that instructions changing the document type already were.

This works sentence by sentence. A line such as "match the full word only, and write all dates as YYYY-MM-DD" keeps the date half with the reader and sends only the first half to the matching engine.

You will see this in your reports. Such an instruction is listed as applied, against the matching engine, with a note of what it governed, rather than appearing as an instruction the reader never applied.

Seeing What Happened

Everything appears in the enrichment view in the console, next to the rules themselves:

each matching instruction, and which rules and conditions it governed
whether it made matching stricter or more forgiving
an amber "had no effect on this document" where an instruction governed nothing it could change. This is the case that is easiest to hide: if you ask for article codes to match in full but the rule you had in mind checks a different field, you find out rather than assuming it is working
matching instructions that did nothing because they did not say which rules they meant, with the wording that would make them work
fields left unchanged because two possible matches disagreed
for each individual change, whether a forgiving match is what allowed it

The same detail is available in enrichment_report on the API response.

Supported Configurations and Options

Configuration	Detail
Where it is written	Your custom instructions, as plain language
Syntax required	None. No rule numbers, no operators, no structured format
Required element	A reference stating that the instruction addresses transformation rules or a supporting-file lookup
Scoping options	All transformations, all file-based rules, a named file, a written field, a read field
Granularity	Per condition. Conditions not named keep their existing behavior
Stricter options	Whole-word matching, case-sensitive matching, exact match instead of contains
Forgiving options	Ignore punctuation, ignore accents, allow small typos, treat equals as contains, search the whole document
Combining options	Multiple changes can be requested in one instruction
Applies to rejection rules	Stricter changes yes, forgiving changes no
Configuration required	None. Live for all accounts with no integration changes

Other Technical Specifications

Parameter	Detail
Default matching behavior	Substring match on any part of the text
Minimum match length for forgiving matches	At least three letters or digits on both sides
Typo tolerance	One or two characters of difference
Forgiving match write behavior	Fills empty fields only. Never overwrites an existing or rule-produced value
Ambiguous forgiving matches	No value written, and the reason reported
Instruction classification	Each sentence is classified as a reading instruction or a matching instruction before its wording is interpreted
Visibility	Enrichment view in the console, and `enrichment_report` on the API response
Default when no instruction is written	Every rule behaves exactly as it did before

Notes

An instruction that describes what should change but does not say which rules it addresses has no effect. It is reported on the document, with suggested wording, rather than being applied on a guess.
Instructions that tell Docupath where on the page to find a value are reading instructions and are never treated as matching instructions, even when they use words like "exactly" or "ignoring capital letters".
Narrow instructions are safer than broad ones. A broad instruction such as "for transformations, match whole words" governs every condition on the document, which may include many rules you did not intend to change. Name the field wherever possible.
Forgiving matches cannot repair a field that already holds a wrong value, because they only fill blanks. Where a wrong value is being written, a stricter instruction or a rule change is the correct fix.
A forgiving instruction has no effect on rejection rules. A rejection outcome always rests on an exact comparison.
An amber "had no effect on this document" entry usually means the instruction named a different field or file than the rule actually uses. Check the rule's conditions before rewording the instruction.
Matching behavior and rule evaluation order are separate features. If a value is being overwritten rather than mismatched, see Transformation Rule Evaluation Order.

Known Limitations and Edge Cases

Where two forgiving matches are equally plausible, the field is deliberately left empty. No tie-break is attempted.
A condition looking for a very short value, such as a single punctuation character, cannot be made forgiving, because the three-character minimum on both sides is not met.
A single sentence can contain both a matching instruction and an instruction for the extraction AI. These are separated automatically, so each half reaches the right place, but a sentence written this way is harder to audit later than two separate sentences.

Matching Instructions For Transformation Rules