Running Matches

A matching run executes a matching configuration against its reference dataset, scoring every scoped document. Runs are processed asynchronously on a dedicated job queue, so they never block your workflow: trigger a run, keep working, and monitor progress in real time with the number of documents processed. In-flight runs can be cancelled, and partial results from documents already processed are preserved.

Manual runs vs. smart runs

There are two types of runs. Manual runs use only the deterministic matching strategies (exact, fuzzy, date_range, numeric_range) and complete quickly. Smart runs execute a previously generated AI strategy against the documents scoped by the config, adding an AI resolution pass: an embedding-based similarity search identifies promising candidates for each low-confidence document, and a Haiku LLM resolver evaluates each candidate in context to improve match quality. A smart run requires a strategy_id from POST /v1/matching/strategies/generate.

For best results, start with a manual run to establish a baseline, then use a smart run if many documents have low-confidence matches. Smart runs take longer because the AI resolver evaluates each ambiguous candidate, but they can significantly improve match quality for data with inconsistent formatting, abbreviations, or multilingual content.

1. Open the advanced off-nav matching surface (/assemble/matching) and select a matching configuration.
2. Click Run for a standard match, or Smart Run to execute a generated AI strategy (API: POST /v1/matching/configs/:id/run or /smart-run with a strategy_id).
3. Monitor progress in real time (API: GET /v1/matching/runs/:id/progress).
4. Cancel a queued or running job at any time if needed; partial results are preserved.
5. Review results when the run completes.

# Start a standard matching run:
curl -X POST https://api.talonic.com/v1/matching/configs/CONFIG_UUID/run \
  -H "Authorization: Bearer $TALONIC_API_KEY"
# -> 201 { "id": "…", "status": "queued", ... }

# Start a smart run (executes a generated AI strategy):
curl -X POST https://api.talonic.com/v1/matching/configs/CONFIG_UUID/smart-run \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "strategy_id": "c9d0e1f2-…" }'

# Check progress:
curl -s https://api.talonic.com/v1/matching/runs/RUN_UUID/progress \
  -H "Authorization: Bearer $TALONIC_API_KEY"
# -> { "status": "running", "processed": 180, "total": 245, "percentage": 73.5 }

# Cancel if needed (queued or running only; partial results preserved):
curl -X POST https://api.talonic.com/v1/matching/runs/RUN_UUID/cancel \
  -H "Authorization: Bearer $TALONIC_API_KEY"

AI resolution on completed runs

You can also trigger an AI resolution pass on a completed run without re-running the entire job. The POST /v1/matching/runs/{id}/ai-resolve endpoint targets the run's review band, meaning the low-confidence results from the initial matching pass, and applies the embedding-based similarity search plus Haiku LLM evaluation to upgrade their scores. This is more efficient than a full smart run when you only need to improve a small subset of borderline results. The run must have an associated strategy for AI resolution to be available.