Skip to main content
POST
Trigger a matching run

Authorizations

Authorization
string
header
required

Bearer token authentication (format: "Bearer {token}")

Headers

X-Request-Id
string

A unique identifier for tracing the request across services.

X-Idempotency
string

Optional idempotency key for safe retries. Matcher reads the key only from this header, and only when you send one. A request that carries a key only in X-Idempotency-Key or Idempotency-Key is refused with 400 (MTCH-0015), and nothing is processed. If the same key is sent again and the original request was already processed, the stored response is returned with X-Idempotency-Replayed: true. A malformed key returns 400, a key whose first request is still in progress returns 409, and an idempotency storage failure returns 500. These refusals are problem documents.

Path Parameters

contextId
string<uuid>
required

The unique identifier of the reconciliation context. Reconciliation context ID

Body

application/json

Run match payload

mode
enum<string>
required

Execution mode

Available options:
DRY_RUN,
COMMIT
Example:

"DRY_RUN"

async
boolean

Submit asynchronously: when true the run is queued (status QUEUED) and executed by the worker; when false/omitted the run executes in-request and the response carries the completed run (terminal status). Both paths return HTTP 202; distinguish by the response status. Poll GET /v1/matching/runs/{runId} for async progress.

Example:

false

Response

Indicates that the request was accepted for processing.

runId
string<uuid>
required

Identifier of the match run that was triggered

Example:

"550e8400-e29b-41d4-a716-446655440000"

status
enum<string>
required

Status of the run at acceptance: QUEUED (async submit, awaiting worker pickup), COMPLETED (finished synchronously), or FAILED (errored synchronously). A synchronous run is already terminal; an async run is QUEUED. Poll GET /v1/matching/runs/{runId} for async progress (PROCESSING/FINALIZING/COMPLETED)

Available options:
QUEUED,
COMPLETED,
FAILED
Example:

"COMPLETED"