The AI Data Match action uses AI to compare data against a lookup list and find the best match. Its job is to resolve an entity to its unique ID — the Vendor Code behind a vendor name, the Customer Number behind a bill-to address. It is useful for tasks like Vendor Matching in invoice processing and is an AI variation of the Lookup Table Validator. It can match either from the Record's index field values or directly from the document image itself.


The settings are on four tabs. Match sets what is matched: the Record's field values or the party shown on a document. Candidates sets what it is matched against: a search of the Record Type that holds the entities, or a list you supply. Results sets where the matched key is written. AI Level sets the AI quality and any extra instructions.


AZURE ONLY: This is an AI action and runs only on Azure-hosted / AI-licensed sites.


Candidates

Candidates From chooses where the possible matches come from.

Search a Record Type

The action looks up only the few Records that resemble the entity, so there is no list to build or keep up to date. Use this whenever the entities are kept in a Record Type, such as a Vendors or Customers Record Type.

  • Record Type - The Record Type that holds the entities.
  • Search Fields - The fields to look in. Add the name field, plus any field that holds an account number, tax ID, or phone number. Every value is tried in every field.
  • No Match Phrases Field - Optional. A field that holds phrases ruling a Record out: when one of them appears on the document, that Record is dropped before the AI sees it. This is how two similar Records are kept apart, such as two divisions of the same company that differ only by their remit-to address. Put each phrase in double quotes, with a space between them, to list several - for example "Remit to PO Box 77" "Eastern Division" - or leave out the quotes to use the whole value as one phrase. Phrases match whole words and ignore capitalization and punctuation. When matching on index fields, the phrases are looked for in the Matching Fields' values instead of the document. The document must have been OCR'd for phrases to be checked; if it has not, nothing is dropped and the AI is told what the field means instead.
  • Key Field - The field whose value is returned as the match, usually the Vendor ID or Customer Number. Enter RecordID to return the matched Record's ID instead.


In Index mode the action searches for the values of the Matching Fields. In Image mode it first reads the named entity off the document - its name, other ways the name may be written, and any account number or similar identifier printed near it - and then searches for those.


Names are found by how they begin, so "ACME Corporation, Inc." finds "ACME Corp". Identifiers must match exactly. When nothing is found, the action tries the first word of the name on its own. A misspelled first word cannot be found this way, which is why an identifier field in Search Fields is so valuable: an account number printed on the document finds the right Record even when the name was misread.


If nothing is found, the action does not guess: it marks the Record as not matched and the workflow carries on. See When There Is No Match below.


Candidate Data list

  • Candidate Data - The lookup list to match against. This can be either CSV or JSON; the format is auto-detected and JSON is converted to CSV automatically before it is sent to the AI (CSV is cheaper and more efficient to transfer). This is normally a variable that returns the data. Use [DOCUMENTEXT(ID)] to load the data from a Document, or [SERVERDATA(name)] to load it from a cached Server Data. See Working with Large Lookup Lists below if your list runs to hundreds or thousands of rows.
  • Key Field - The name (header/column) of the candidate data that holds the key value for the match. When a match is found, this column's value is returned as the match result. For Vendor matching this is usually the Vendor Code or Vendor ID.


Include any column that could help identify the entity, not just its name. Columns holding an account number, customer number, tax ID, or phone number are especially valuable, because an exact hit on one of those identifies the right row instantly even in a very large list where names alone are ambiguous.



Match Using (Index Fields or Document Image)

Match Using — Chooses where the match data comes from. Toggle ON to match using the Record's INDEX FIELDS; toggle OFF to match using the DOCUMENT IMAGE. Existing actions default to Index mode. These settings are on the Match tab.


Index mode (Match Using = Index Fields)

  • Matching Fields — The list of Record field names to send into the action for matching. Enter one field name per line. Send anything that helps identify the match such as Full Address, Phone, or Fax, as long as the same information also exists in the candidate data. Sending values that cannot help the match does not improve results and only adds tokens.


Image mode (Match Using = Document Image)

Use Image mode when you need the AI to read a party's identity off the document itself — for example to determine which vendor an invoice belongs to before you know how to index it. The AI reads the identity from the document (company name, address, identifiers) and matches it to the candidate list. Because a document often shows several parties (vendor, bill-to customer, ship-to, and so on), you must tell the AI which one to match.

  • Entity to Match — Names the entity/role for the AI to identify on the document and match, such as Vendor, Customer, or Employee. This is required in Image mode. It removes the ambiguity of which party on the page to match against the list.
  • Document to Match — Selects which of the Record's documents to send, by Category, SubCategory, and Name. Leave a selector blank to match any value for that part. The first matching document is used.
  • Pages to Send — Limits which pages of the document are sent to the AI. See the section below.

Note: In Image mode the Record's index field values are NOT sent — the match is based purely on the document and the named entity. Use Index mode when you want to match on already-captured field values.

Pages to Send

This setting appears in Image mode only, because Index mode sends no document at all.


Leave it blank to send every page. Enter 1 for the first page only, 1,2,5 for a list, 1-3 for a range, or mix them — 1,5-7 works. Pages are counted from 1, and the range is applied after any conversion to PDF, so it means the same thing whatever the original file format was. Numbers that do not exist in the document are simply ignored. The box accepts variables, so the page list can come from a value on the Record rather than being fixed on the action.


For this action a page range is almost always worth setting. The entity being matched — the vendor's letterhead, the customer's bill-to block — is on the first page of nearly every business document, and the pages after it contribute nothing to the match while costing the same to read. Image mode also reads the document twice when the candidate list is large (see A Note on Image Mode Cost below), so every page you leave out is saved twice over.


The named entity has to be on a page you sent. If AIDataMatch_Outcome starts reporting that the entity could not be identified on the document, check the page range first - a letterhead on page 2 of a document sent as page 1 only is invisible to the AI.


Writing the Match to a Field

By default the action records its results in the AIDataMatch_ values listed under Returned Values, and getting the matched key onto the Record itself takes a follow-on Set Data action. These settings are on the Results tab.



These two settings let the action write the result directly:

  • Write Match To — The Record field that receives the matched key value. Leave blank to keep the previous behavior of recording the AIDataMatch_ values only.
  • Minimum Confidence — How sure the AI must be before the match is written to that field. Choose High, Medium, or Low. A match below the floor is still recorded in the AIDataMatch_ values, and AIDataMatch_Outcome explains in plain language why nothing was written, so the Record can be routed for human review rather than silently carrying a guess.


Set this floor deliberately. A weak match sitting in a diagnostic value is harmless, but the same weak match written into a real field flows into every decision and lookup made downstream of it.

Working with Large Lookup Lists

When the entities are kept in a Record Type, the simplest answer to a large lookup is Search a Record Type, described under Candidates above: only the few Records that resemble the entity are ever read. The rest of this section applies to a Candidate Data list.


Sending a large lookup list to the AI on every document is slow and expensive, so the action narrows the list automatically. Lists of roughly 50 rows or fewer are sent whole, exactly as before. Larger lists are reduced to the most plausible candidates before the AI is asked to choose. This is automatic and needs no configuration.


Narrowing compares what is known about the entity against every column of every row, so it is worth including identifier columns in your candidate data as described above. The narrowing pass is deliberately generous — it keeps anything that plausibly resembles the entity and lets the AI make the actual decision — and AIDataMatch_CandidateCount and AIDataMatch_NarrowedCount report how many rows the list started and ended with.


If nothing in the list resembles the entity at all, the action reports no match rather than matching against an arbitrary selection of rows. This is intentional: no answer is better than a confident wrong one.


Caching a large list with Server Data

Loading thousands of rows from a Record Type on every document is wasteful when the underlying data changes daily at most. The efficient pattern is to build the list once on a schedule and read it from cache in this action.


Create a recurring workflow that runs the Server Field Update action with the Server Data name in Variable (for example AILinkCache_Vendors) and the lookup query in Value (for example [DMGET2(3|5000||VendorNum^VendorName^City^State^AcctNo)]). Then set this action's Candidate Data to [SERVERDATA(AILinkCache_Vendors)].


Refresh timing is yours to choose — schedule the rebuild for whatever interval matches how often your data actually changes. An entity added since the last refresh will not be in the cache and will not match until the next rebuild.


AI Level

  • Quality — The AI quality to use for this action.
    • Economy works best for clean, electronic PDFs. It is not best for skewed, scanned, or complex documents. Cost: LOWEST. (Economy is not available in Image mode, which needs a vision-capable model; it is automatically raised to Balanced.)
    • Balanced works best for a combination of scanned and/or electronic documents that may be fuzzy or slightly skewed. Cost: MIDDLE.
    • Maximum works best for complex, skewed, or ambiguous data that requires more logic to resolve. Cost: HIGHEST.

Extra Instructions

Extra Instructions is on the AI Level tab. It holds any extra guidance for the AI to follow. The action already knows the task; this is anything additional that helps, such as "Full address field is more important than phone number".


Returned Values

  • AIDataMatch_Result - What became of the match: MATCHED (a match at or above the Minimum Confidence), LOWCONFIDENCE (a match below it), or NOMATCH (no match at all). This is the value to route the next steps on.AIDataMatch_MatchKey — The key value that was returned (for example the Vendor ID).
  • AIDataMatch_Success — true if the match succeeded or false if it did not.
  • AIDataMatch_Confidence — low, medium, or high.
  • AIDataMatch_Reason — The reason the match was chosen.
  • AIDataMatch_Outcome - The result in plain language: what was matched and whether it was written to the field named in Write Match To, or why there was no match.
  • AIDataMatch_Col_<Column> - Every column of the matched row, one value per column of your candidate data. For example a candidate list with a City column produces AIDataMatch_Col_City. With Search a Record Type there is one value per field of that Record Type, plus AIDataMatch_Col_RecordID holding the matched Record's ID. See Using the Rest of the Matched Row below.
  • AIDataMatch_CandidateCount — How many rows the candidate list contained.
  • AIDataMatch_NarrowedCount — How many rows were actually sent to the AI after narrowing. Equal to AIDataMatch_CandidateCount when the list was small enough to send whole.
  • AIDataMatch_Seed — In Image mode with a large list, what the AI read off the document before narrowing, including any identifiers it found. Useful for understanding why a match did or did not happen.
  • AIDataMatch_AlternateCount — The number of alternate matches, in order of match confidence.
  • AIDataMatch_AlternateMatchKey_# — The #th alternate's key value.
  • AIDataMatch_AlternateConfidence_# — The #th alternate's confidence value.
  • AIDataMatch_AlternateReason_# — The #th alternate's matching reason.


Using the Rest of the Matched Row

When a match is found, every column of the matched row is written back as AIDataMatch_Col_<Column>. This means a follow-on action can use the rest of the entity's information without looking it up again.


This covers two common needs. When an entity is identified by more than one value — a Vendor Number plus a Division Code, say — both are available as separate values to use however your workflow requires. And when you want related information copied onto the Record, such as a vendor's address or payment terms, a follow-on Search & Update action can write those values to your Record fields, either from the AIDataMatch_Col_ values directly or by searching the entity's Record Type on the matched key.


Typical Sequence

A typical AI sequence is to use AI Invoice Extraction to gather the data, Invoice Indexing to index those values to fields, then AI Data Match to resolve the vendor name to a Vendor ID for maximum decision-flow precision. When you do not yet have reliable field values, use AI Data Match in Image mode to identify the vendor directly from the document first.


When There Is No Match

Finding no match does not stop the workflow. The action sets AIDataMatch_Result to NOMATCH, explains why in AIDataMatch_Outcome, leaves the field named in Write Match To unchanged, and the workflow carries on, so the steps that follow can send the Record for review. There is no match when:

  • the named entity could not be read from the document in Image mode - the page was blank, illegible, or simply did not show that party. A page range that excludes the page carrying the entity produces this same result.
  • none of the Matching Fields had a value in Index mode.
  • no candidate in the Candidate Data list resembled the entity closely enough to be worth matching against.
  • with Search a Record Type, no Record matched what the action searched for. The workflow log shows each value searched and the fields searched in.
  • with Search a Record Type, nothing known about the entity was long enough to search for - every value was shorter than three characters.
  • with Search a Record Type, every Record that was found was ruled out by its No Match phrases.
  • the AI found no candidate that was a plausible match.


A match below the Minimum Confidence sets AIDataMatch_Result to LOWCONFIDENCE. The match is recorded in the AIDataMatch_ values for review, and the field named in Write Match To is left unchanged.


To try another way of matching when this one does not find the entity - the Lookup Table REVERSE Validator, for instance - add that action after this one and limit it to Records where AIDataMatch_Result is not MATCHED.


The action still fails, following its Stop on Error setting, when something prevents it from running at all: the AI could not be reached, the document to match was not found, or the settings are incomplete.


A Note on Image Mode Cost

In Image mode with a large candidate list, the document is read twice — once to identify the entity so the list can be narrowed, and once to match it against the narrowed candidates. This roughly doubles the page reading cost of the action compared to Index mode, and is the reason Image mode is more expensive per document. It remains far cheaper than sending a large lookup list on every run. Limiting Pages to Send is the most effective way to reduce this cost.


NOTE ON (AI): All AI processing will incur extra fees. Check with your sales rep for more information.