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.


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


Candidate Data

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


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 matching starts failing with "the entity could not be read from 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 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

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

Advanced

  • Extra Instructions — 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_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 — Plain-language description of what was written to the field named in Write Match To, or why nothing was. Only present when Write Match To is set.
  • 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. 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 the Action Does Not Match

The action reports a failure, rather than quietly continuing, in these cases. Each is a signal that the Record needs attention rather than something to ignore.

  • 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 failure.
  • No candidate in the list resembled the entity closely enough to be worth matching against.


A match that succeeds but falls below the Minimum Confidence floor is not a failure. The action completes, the AIDataMatch_ values record what was found, and the field named in Write Match To is left unchanged.


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.