> ## 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. # 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. ## OpenAPI ````yaml en/openapi/v3-current/matcher.yaml post /v1/matching/simulate 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/simulate: post: tags: - Matching summary: Simulate a match rule against a context (read-only dry run) description: >- 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. operationId: simulateMatchRule requestBody: content: application/json: schema: $ref: '#/components/schemas/SimulateMatchRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SimulateMatchResponse' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error security: - BearerAuth: [] components: schemas: SimulateMatchRequest: additionalProperties: false properties: contextId: description: Context ID whose transactions the rule is simulated against format: uuid type: string rule: $ref: '#/components/schemas/SimulateRuleDefinition' description: Inline candidate rule to preview. Provide this OR ruleId, not both. ruleId: description: >- Identifier of an existing configured rule to preview. Provide this OR rule, not both. format: uuid type: string sampleLimit: default: 25 description: Maximum number of would-match pairs to return in the sample format: int64 maximum: 200 minimum: 1 type: integer required: - contextId type: object SimulateMatchResponse: additionalProperties: false properties: matchedGroups: description: Number of 1:1 groups the rule would form across the context examples: - 12 format: int64 minimum: 0 type: integer ruleId: description: >- Identifier of the previewed rule. Empty for an inline candidate rule (not persisted). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string ruleType: description: Strategy of the previewed rule examples: - EXACT type: string sample: description: Bounded sample of would-match pairs (highest score first) items: $ref: '#/components/schemas/SimulateMatchPairResponse' maxItems: 200 type: - array - 'null' sampleTruncated: description: Whether matchedGroups exceeds the returned sample length examples: - false type: boolean unmatchedLeft: description: Left-side transactions that would remain unmatched examples: - 3 format: int64 minimum: 0 type: integer unmatchedRight: description: Right-side transactions that would remain unmatched examples: - 5 format: int64 minimum: 0 type: integer required: - ruleType - matchedGroups - unmatchedLeft - unmatchedRight - sampleTruncated - sample type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -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 SimulateRuleDefinition: additionalProperties: false properties: config: additionalProperties: {} description: >- Rule configuration, same shape as a stored match rule's config (e.g. matchAmount, matchCurrency, tolerance settings) type: object type: description: Rule strategy of the inline candidate rule examples: - EXACT type: string required: - type - config type: object SimulateMatchPairResponse: additionalProperties: false properties: amountDelta: description: right.amount - left.amount as a signed decimal string examples: - '0.00' type: string dateDeltaDays: description: Signed whole-day difference (right - left) in UTC days examples: - 0 format: int64 type: integer left: $ref: '#/components/schemas/CandidateTransactionView' description: Left-pool transaction (the rule's left side) the pair would group right: $ref: '#/components/schemas/CandidateTransactionView' description: Right-pool transaction (the rule's right side) the pair would group score: description: Engine confidence score for this pair (0..100) examples: - 90 format: int64 maximum: 100 minimum: 0 type: integer why: $ref: '#/components/schemas/CandidateWhy' description: Per-component rationale for the score required: - left - right - 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}")' ````