Running Matches

Execute a matching run against a reference dataset. Matching runs are processed asynchronously via a dedicated job queue, so they do not block your workflow. You can monitor progress from the matching page with real-time updates showing the number of documents processed and estimated time remaining, and cancel running jobs if needed — partial results from documents already processed are preserved.

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 add an AI resolution pass — after the initial matching, 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.

Matching runs are processed asynchronously via a dedicated BullMQ job queue, so they do not block your workflow. You can continue working in the platform while a run executes in the background. The matching page shows real-time progress with the number of documents processed and estimated time remaining. You can also trigger an AI resolution pass on a completed run using the POST /matching/runs/:id/ai-resolve endpoint to upgrade specific low-confidence results without re-running the entire job.

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. Navigate to the Matching page and select a matching configuration.
2. Click Run for a standard match or Smart Run for AI-enhanced matching.
3. Monitor progress in real-time on the matching page.
4. Cancel the run 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/cfg_001/run \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Start a smart run with AI resolution:
curl -X POST https://api.talonic.com/v1/matching/configs/cfg_001/smart-run \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Check progress:
curl -s "https://api.talonic.com/v1/matching/runs/mrun_001/progress" \
  -H "Authorization: Bearer $TALONIC_API_KEY"
# -> { "processed": 180, "total": 245, "estimated_remaining_ms": 32000 }

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

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 specifically targets low-confidence results from the initial deterministic matching pass and applies the embedding-based similarity search plus Haiku LLM evaluation to upgrade their scores. This is more efficient than running a full smart run when you only need to improve a small subset of borderline results. The AI resolver evaluates each ambiguous candidate in context, considering the full set of field comparisons and the document content, to make a more informed match decision than the deterministic strategies alone.