> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# List match candidates for a transaction

> 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.



## OpenAPI

````yaml en/openapi/v3-current/matcher.yaml get /v1/matching/candidates
openapi: 3.1.0
info:
  title: Matcher APIs
  description: >-
    Complete API reference for the Matcher reconciliation engine, providing
    automated transaction matching between Midaz Ledger and external systems.
  version: 4.1.0
  license:
    name: Elastic License 2.0
    url: https://www.elastic.co/licensing/elastic-license
servers:
  - url: https://matcher.sandbox.lerian.net
security: []
paths:
  /v1/matching/candidates:
    get:
      tags:
        - Matching
      summary: List match candidates for a transaction
      description: >-
        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.
      operationId: listMatchCandidates
      parameters:
        - description: Context ID the transaction belongs to
          explode: false
          in: query
          name: contextId
          required: true
          schema:
            description: Context ID the transaction belongs to
            format: uuid
            type: string
        - description: >-
            Target transaction to find counterparts for. For an exception,
            resolve its transaction id first, then pass it here.
          explode: false
          in: query
          name: transactionId
          required: true
          schema:
            description: >-
              Target transaction to find counterparts for. For an exception,
              resolve its transaction id first, then pass it here.
            format: uuid
            type: string
        - description: Maximum number of ranked proposals to return
          explode: false
          in: query
          name: limit
          schema:
            default: 50
            description: Maximum number of ranked proposals to return
            format: int64
            maximum: 200
            minimum: 1
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidateProposalsResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
components:
  schemas:
    CandidateProposalsResponse:
      additionalProperties: false
      properties:
        items:
          description: Ranked candidate proposals (highest score first)
          items:
            $ref: '#/components/schemas/CandidateProposalResponse'
          maxItems: 200
          type:
            - array
            - 'null'
        targetTransactionId:
          description: The transaction counterparts were proposed for
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
      required:
        - targetTransactionId
        - items
      type: object
    Detail:
      additionalProperties: false
      properties:
        code:
          description: >-
            Stable, machine-readable domain error code scoped to the emitting
            service (format: <SERVICE>-NNNN).
          examples:
            - ERR-0001
          type: string
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
            - array
            - 'null'
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: >-
            A short, human-readable summary of the problem type. This value
            should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
      type: object
    CandidateProposalResponse:
      additionalProperties: false
      properties:
        amountDelta:
          description: candidate.amount - target.amount as a signed decimal string
          examples:
            - '0.00'
          type: string
        dateDeltaDays:
          description: Signed whole-day difference (candidate - target) in UTC days
          examples:
            - 0
          format: int64
          type: integer
        ruleId:
          description: Identifier of the rule that produced the best score for this pair
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        ruleType:
          description: Strategy of the rule that produced the best score
          examples:
            - EXACT
          type: string
        score:
          description: Engine confidence score for this pair (0..100)
          examples:
            - 90
          format: int64
          maximum: 100
          minimum: 0
          type: integer
        transaction:
          $ref: '#/components/schemas/CandidateTransactionView'
          description: The proposed counterpart transaction
        why:
          $ref: '#/components/schemas/CandidateWhy'
          description: Per-component rationale for the score
      required:
        - transaction
        - ruleId
        - ruleType
        - score
        - why
        - amountDelta
        - dateDeltaDays
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    CandidateTransactionView:
      additionalProperties: false
      properties:
        amount:
          description: Candidate amount as a decimal string
          examples:
            - '100.50'
          type: string
        baseAmount:
          description: >-
            Candidate base-currency amount, when the transaction was
            FX-converted
          examples:
            - '100.50'
          type: string
        currency:
          description: Candidate ISO 4217 currency code
          examples:
            - USD
          type: string
        date:
          description: Candidate transaction date (RFC 3339 timestamp)
          examples:
            - '2025-01-15T10:30:00Z'
          type: string
        externalId:
          description: External reference/id of the candidate transaction
          examples:
            - INV-1234
          type: string
        id:
          description: Candidate transaction ID (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        sourceId:
          description: Source the candidate belongs to (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440001
          type: string
      required:
        - id
        - sourceId
        - amount
        - currency
        - date
      type: object
    CandidateWhy:
      additionalProperties: false
      properties:
        amountMatch:
          description: >-
            Whether the amounts are literally equal on the matched rule's sign
            axis (not merely within tolerance)
          examples:
            - true
          type: boolean
        currencyMatch:
          description: Whether the currency codes are literally equal and both non-empty
          examples:
            - true
          type: boolean
        dateMatch:
          description: >-
            Whether both transactions fall on the same UTC calendar day (not the
            full DATE_LAG window)
          examples:
            - true
          type: boolean
        matchedKeys:
          description: >-
            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.
          items:
            $ref: '#/components/schemas/CandidateMatchedKey'
          type:
            - array
            - 'null'
        referenceScore:
          description: Graded 0..1 reference-similarity contribution
          examples:
            - 1
          format: double
          maximum: 1
          minimum: 0
          type: number
      required:
        - amountMatch
        - currencyMatch
        - dateMatch
        - referenceScore
      type: object
    CandidateMatchedKey:
      additionalProperties: false
      properties:
        agreed:
          description: >-
            Whether the two transactions agree on this key under the field's
            configured mode/tolerance — the engine's own per-field gate decision
          examples:
            - true
          type: boolean
        field:
          description: Name of the configured composite match field (metadata key)
          examples:
            - payment_id
          type: string
      required:
        - field
        - agreed
      type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Bearer token authentication (format: "Bearer {token}")'

````