---
title: "List match candidates for a transaction"
method: GET
path: "/v1/matching/candidates"
tags: ["Matching"]
---

# List match candidates for a transaction

`GET /v1/matching/candidates`

Returns a ranked list of opposite-side unmatched transactions the engine considers plausible counterparts for the target transaction, each with a confidence score, the rule that drove it, a per-component rationale (the "why"), and amount/date deltas. Powers the exception-resolution and manual-match candidate pickers. Scope: proposals are scored by the deterministic rule engine over raw transaction amounts and do NOT apply run-time fee normalization or the FX-variance band; only 1:1 pairwise counterparts are returned.

## Query parameters

- `contextId` string, uuid, required — Context ID the transaction belongs to
- `transactionId` string, uuid, required — Target transaction to find counterparts for. For an exception, resolve its transaction id first, then pass it here.
- `limit` integer — Maximum number of ranked proposals to return

## Response `200`

OK

- CandidateProposalsResponse
  - `items` CandidateProposalResponse[], nullable, required — Ranked candidate proposals (highest score first)
    - `amountDelta` string, required — candidate.amount - target.amount as a signed decimal string
    - `dateDeltaDays` integer, required — Signed whole-day difference (candidate - target) in UTC days
    - `ruleId` string, required — Identifier of the rule that produced the best score for this pair
    - `ruleType` string, required — Strategy of the rule that produced the best score
    - `score` integer, required — Engine confidence score for this pair (0..100)
    - `transaction` CandidateTransactionView, required
      - `amount` string, required — Candidate amount as a decimal string
      - `baseAmount` string — Candidate base-currency amount, when the transaction was FX-converted
      - `currency` string, required — Candidate ISO 4217 currency code
      - `date` string, required — Candidate transaction date (RFC 3339 timestamp)
      - `externalId` string — External reference/id of the candidate transaction
      - `id` string, required — Candidate transaction ID (UUID)
      - `sourceId` string, required — Source the candidate belongs to (UUID)
    - `why` CandidateWhy, required
      - `amountMatch` boolean, required — Whether the amounts are literally equal on the matched rule's sign axis (not merely within tolerance)
      - `currencyMatch` boolean, required — Whether the currency codes are literally equal and both non-empty
      - `dateMatch` boolean, required — Whether both transactions fall on the same UTC calendar day (not the full DATE_LAG window)
      - `matchedKeys` CandidateMatchedKey[], nullable — Per-key agreement for the matched rule's configured composite match fields (matchFields), in field-name order. Empty when the matched rule declares no active matchFields.
        - `agreed` boolean, required — Whether the two transactions agree on this key under the field's configured mode/tolerance — the engine's own per-field gate decision
        - `field` string, required — Name of the configured composite match field (metadata key)
      - `referenceScore` number, double, required — Graded 0..1 reference-similarity contribution
  - `targetTransactionId` string, required — The transaction counterparts were proposed for

## Other responses

- `default` — Error

---

[API](https://skmtc.net/lerian/apis/identity-plugin.md) · [All operations](https://skmtc.net/lerian/apis/identity-plugin/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lerian/identity-plugin/versions/25daba385532/schema)