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

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

cURL

curl --request POST \
  --url https://matcher.sandbox.lerian.net/v1/matching/simulate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contextId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "ruleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sampleLimit": 25
}
'

200

Example

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

Autorizaciones

Authorization · string · header · requerido

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

Cuerpo

application/json

contextId · string<uuid> · requerido

Context ID whose transactions the rule is simulated against

rule · object

Inline candidate rule to preview. Provide this OR ruleId, not both.

Show child attributes

ruleId · string<uuid>

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

sampleLimit · integer<int64> · predeterminado: 25

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

Rango requerido: 1 <= x <= 200

Respuesta

200

application/json

OK

matchedGroups · integer<int64> · requerido

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

Rango requerido: x >= 0

Ejemplo:

12

ruleType · enum<string> · requerido

Strategy of the previewed rule

Opciones disponibles: EXACT, TOLERANCE, DATE_LAG, FUZZY

Ejemplo:

"EXACT"

sample · object[] | null · requerido

Bounded sample of would-match pairs (highest score first)

Maximum array length: 200

Show child attributes

sampleTruncated · boolean · requerido

Whether matchedGroups exceeds the returned sample length

Ejemplo:

false

unmatchedLeft · integer<int64> · requerido

Left-side transactions that would remain unmatched

Rango requerido: x >= 0

Ejemplo:

3

unmatchedRight · integer<int64> · requerido

Right-side transactions that would remain unmatched

Rango requerido: x >= 0

Ejemplo:

5

ruleId · string

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

Ejemplo:

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