Matchers

A Matcher compares the line items of several documents side by side. It lines up the rows that describe the same item, even when each document words it differently, puts their prices or quantities in one table and marks the winner of every row.

A Matcher sits on top of one flow. The flow does the extraction; the Matcher reads the results of two or more completed runs of that flow and builds one comparison. Each execution is called a Match. Three supplier quotes for the same request, for example, become one table with a price column per supplier and a Champion column naming the cheapest supplier on each line.

• Comparing quotes from several suppliers for the same list of items and picking the cheapest per line
• Checking an invoice against its purchase order, line by line, to catch price differences
• Benchmarking new offers against a reference price list or a previous order
• Finding the highest value per item across documents, such as the best rebate or the largest quantity

If you need pass or fail rules across different kinds of documents (dates, totals, references) rather than a line-by-line price table, use an Inspector instead.

A Matcher is defined by the role each field of its flow plays. The options come from the flow you pick, filtered by what each role accepts.

Use Benchmark when one document is the reference (a purchase order, your price list, last year's contract). Use Multilateral when the documents are peers, such as quotes from competing suppliers.

1. 1Go to Matchers in the main navigation and click New Matcher.
2. 2Answer “Which flow's runs will you compare?”: From a flow (pick the flow and a name, then click Next), From an existing matcher (duplicates its configuration with Create copy) or Start from scratch.
3. 3In Matcher Info, check the name (at least 3 characters), add an optional description and confirm the Flow. All compared runs must belong to this flow.
4. 4In Fields, choose the Mode, the Identifier field, Match field, Comparison field, the Champion rule and any Context fields.
5. 5Optionally fill in Email Output and Webhook (the URL must start with https://), and switch on Human in the Loop if every match should wait for a reviewer.
6. 6Click Create Matcher. You land on the matcher's page, where you can pick reviewers and run your first match.

On the matcher's page, Configuration lets you edit the mode and field roles later, Match History lists every match it has run, and Matcher ID shows the identifier you need for the API. Each match keeps a snapshot of the configuration it ran with, so editing the matcher doesn't change past results.

1. 1Make sure the documents have been processed by the matcher's flow and their runs are Completed.
2. 2On the matcher's page, click Run Match.
3. 3Tick at least two completed runs of the flow.
4. 4For a Benchmark matcher, click the star on one of the selected runs to make it the Benchmark run.
5. 5Click Start Match. The match is queued and its page opens, showing progress until the comparison table is ready.

You can also start matches in other ways:

• By email. In Email Trigger, switch the trigger on and copy the Inbox Address. Email two or more documents (PDF or images) to it: each attachment becomes a run of the flow, and the match starts once they have all finished. The results are sent back as a reply in the same thread, with the table attached as CSV and a PDF report. Email-triggered matches always run in Multilateral mode. Use Allowed Senders to limit who can trigger it.
• From a Subject case. When a matcher is bound to a Subject, the case page lists it under Checks with a Run button that uses the case's completed runs of the matcher's flow.
• In a Pipeline, as a node fed by the runs of upstream flows. See Pipelines.
• Over the API, described below.

A completed match shows a Comparison Table with two columns per participant and a Champion column at the end.

Participant columns are named after the fields and the identifier value: with a match field Item Description, a comparison field Unit Price and a supplier called ACME, you get Item Description-ACME and Unit Price-ACME. A blank pair means that participant had no matching item on that row. The winning participant's columns are highlighted.

Above the table you will find:

• Rows and Cells: the size of the result.
• Warnings: for example a run excluded because its identifier field was empty, two runs merged because they share an identifier, or a comparison value that isn't a number and was left out of the championship.
• Match Info: matcher, mode, runs, creation time and, for email matches, the sender.
• Exports: Export to Bucket, CSV, JSON and a PDF report.

Switch on Human in the Loop on the matcher and pick the reviewers. Every match then pauses at Awaiting approval before its results are released, and the reviewers are notified by email. Only the reviewers you pick can approve or reject.

1. 1Open the match from Human in the Loop (or click Review on the match page).
2. 2The Match Review board shows one column per participant, with the AI's pairings drawn as lines and the source documents alongside.
3. 3Click a card, then a card in another column, to connect them. Click a line to break a link. Use the X to exclude a row from the results entirely.
4. 4Click Approve or Reject.

Members with the HITL Only role can review but can't create matchers or run matches. See Human in the Loop.

• In-app notification to whoever started the match.
• Email Output: the address receives an email when a match completes, with the comparison table attached as CSV.
• Webhook: a POST with the table as JSON (columns, rows, row_warnings, warnings) plus match_id and matcher_id. See Webhooks.

With human review on, outputs are sent only after approval.

Start a match from your own system with your API key. Copy the ID from Matcher ID on the matcher's page.

curl -X POST https://run.tavnit.io/api/matchers/<matcher_id>/run \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"run_ids": ["<run_a>", "<run_b>", "<run_c>"], "benchmark_run_id": "<run_a>"}'

• run_ids: two or more completed runs of the matcher's flow.
• benchmark_run_id: required for Benchmark matchers, and must be one of run_ids. Leave it out for Multilateral.
• The response is 202 with match_id and status (queued). A 402 means your organization can't start new work right now; contact the Tavnit team. A 400 explains what is wrong with the request.
• Configure a Webhook on the matcher to receive the comparison table when the match completes.

Authentication and the other endpoints are covered in API Integration.

• 2 to 10 runs per match, all completed and from the matcher's flow.
• Up to 5,000 result rows per run.
• Email trigger: at least two readable attachments and no more than 10.
• Every member except HITL Only can create, edit and delete matchers and run matches.