Skip to main content

Run Matching

Execute a matching run against reference data asynchronously, or use smart-run for AI-assisted matching that auto-tunes strategies. Poll run status via the run detail endpoint.

Execute a matching run to compare documents against the reference dataset defined in the config. Runs are asynchronous — the endpoint returns immediately with a queued status. Poll the run detail endpoint to track progress and retrieve results.

The smart-run variant uses a pre-generated AI strategy that automatically tunes comparison thresholds and field priorities. This can significantly improve accuracy on datasets with heterogeneous formatting, inconsistent naming, or mixed-language content.

Matching runs are processed via a BullMQ job queue. Large datasets may take several minutes. Use GET /v1/matching/runs/:id/progress to poll for live progress updates while the run is active.
POST/v1/matching/configs/:id/run

Response (Run)

Response fields

idstringMatching run UUID.
matching_config_idstringConfig that triggered this run.
statusstringInitial status: queued.
triggered_bystringHow the run was triggered (manual, scheduled, etc.).
rows_processedinteger | nullNumber of rows processed so far.
rows_matchedinteger | nullNumber of rows that produced a match above threshold.
avg_confidencenumber | nullAverage confidence across matched rows.
started_atstring | nullISO 8601 timestamp when the run began.
completed_atstring | nullISO 8601 timestamp when the run finished.
errorstring | nullError message if the run failed.
created_atstringISO 8601 creation timestamp.
links.selfstringURL to this run.
links.configstringURL to the config that owns this run.

Response (POST /run)

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "matching_config_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "triggered_by": "manual",
  "rows_processed": null,
  "rows_matched": null,
  "avg_confidence": null,
  "started_at": null,
  "completed_at": null,
  "error": null,
  "created_at": "2024-10-02T14:00:00.000Z",
  "links": {
    "self": "/v1/matching/runs/c3d4e5f6-a7b8-9012-cdef-123456789012",
    "config": "/v1/matching/configs/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
POST/v1/matching/configs/:id/smart-run

Response (Smart Run)

Returns the same run object shape as a standard run, with status queued.

Response (POST /smart-run)

{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "matching_config_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "triggered_by": "manual",
  "rows_processed": null,
  "rows_matched": null,
  "avg_confidence": null,
  "started_at": null,
  "completed_at": null,
  "error": null,
  "created_at": "2024-10-02T14:05:00.000Z",
  "links": {
    "self": "/v1/matching/runs/d4e5f6a7-b8c9-0123-defa-234567890123",
    "config": "/v1/matching/configs/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Errors

Error responses

400validation_errorstrategy_id is required for smart-run.
401unauthorizedMissing or invalid API key.
404not_foundNo matching config with this ID exists for your workspace.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Run Detail
Results