Sign in

v1

latestOpenAPI 3.1.02026-07-263644911022.4 KB
Matching

Simulate a match rule against a context (read-only dry run)

Previews how a single rule — an existing configured rule (ruleId) OR an inline candidate rule (rule) — would match a context's unmatched transactions, WITHOUT committing anything. Returns the number of 1:1 groups the rule would form, a bounded sample of would-match pairs (each with a confidence score, a per-component rationale (the "why"), and matched composite keys), and the per-side unmatched counts. Powers the rule-authoring "will this rule actually match?" preview. Scope: scored by the deterministic rule engine over raw transaction amounts; it does NOT apply run-time fee normalization or the FX-variance band, and previews only 1:1 pairwise grouping (no 1:N/N:M allocation). Nothing is persisted; the tenant is taken from the JWT, never the body.

post/v1/matching/simulate

Request body

contextIdstring uuid required

Context ID whose transactions the rule is simulated against

ruleIdstring uuid

Identifier of an existing configured rule to preview. Provide this OR rule, not both.

sampleLimitinteger

Maximum number of would-match pairs to return in the sample

Example request

{
  "rule": {
    "type": "EXACT"
  }
}

Response

OK

matchedGroupsinteger required

Number of 1:1 groups the rule would form across the context

ruleIdstring

Identifier of the previewed rule. Empty for an inline candidate rule (not persisted).

ruleTypestring required

Strategy of the previewed rule

sampleTruncatedboolean required

Whether matchedGroups exceeds the returned sample length

unmatchedLeftinteger required

Left-side transactions that would remain unmatched

unmatchedRightinteger required

Right-side transactions that would remain unmatched

Example response

{
  "matchedGroups": 12,
  "ruleId": "550e8400-e29b-41d4-a716-446655440000",
  "ruleType": "EXACT",
  "sample": [
    {
      "amountDelta": "0.00",
      "left": {
        "amount": "100.50",
        "baseAmount": "100.50",
        "currency": "USD",
        "date": "2025-01-15T10:30:00Z",
        "externalId": "INV-1234",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "sourceId": "550e8400-e29b-41d4-a716-446655440001"
      },
      "right": {
        "amount": "100.50",
        "baseAmount": "100.50",
        "currency": "USD",
        "date": "2025-01-15T10:30:00Z",
        "externalId": "INV-1234",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "sourceId": "550e8400-e29b-41d4-a716-446655440001"
      },
      "score": 90,
      "why": {
        "amountMatch": true,
        "currencyMatch": true,
        "dateMatch": true,
        "matchedKeys": [
          {
            "agreed": true,
            "field": "payment_id"
          }
        ],
        "referenceScore": 1
      }
    }
  ],
  "unmatchedLeft": 3,
  "unmatchedRight": 5
}