Rule suggestions

Matcher can propose config-only match rules from a context’s history using AI, but AI output is never authoritative. Producing a suggestion creates no rule. Matcher creates a rule only when a human approves a suggestion. This guide covers the human-in-the-loop (HITL) rule-suggestion queue.

A global advisor kill-switch and a per-tenant opt-in gate the lane (fail-closed: a non-opted-in tenant gets 403). The egress payload is aggregates only. No raw transaction, money, or PII leaves your deployment.

Produce suggestions

Build aggregate, privacy-safe history features for a context, ask the AI advisor for candidate rules, and enqueue each surviving candidate in the review queue.

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/rule-suggestions" \
  -H "Authorization: Bearer $TOKEN"

The response returns the newly created PENDING_REVIEW reviews (producing them creates no rule):

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contextId": "550e8400-e29b-41d4-a716-446655440000",
      "candidate": {
        "type": "TOLERANCE",
        "priority": 10,
        "config": { "percentTolerance": "0.01" },
        "rationale": "near-miss amounts cluster under 1%",
        "expectedImprovement": "+8% auto-match",
        "confidence": 0.82
      },
      "status": "PENDING_REVIEW",
      "version": 1,
      "createdAt": "2026-06-16T10:30:00Z",
      "updatedAt": "2026-06-16T10:30:00Z"
    }
  ],
  "count": 1
}

Candidate types come from the closed vocabulary: EXACT (strict equality), TOLERANCE (within an amount band), or DATE_LAG (allowing a settlement-date offset). The candidate is config only. It never carries a monetary value or a transaction.

List suggestions

Cursor-paginated list of rule suggestions for a context, optionally filtered by status.

curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/rule-suggestions?status=PENDING_REVIEW&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Query parameters: status (PENDING_REVIEW, APPROVED, REJECTED), limit (1–200), and cursor. Reading the queue egresses nothing.

Approve a suggestion

Approving a PENDING_REVIEW suggestion creates the match rule through the deterministic configuration write path. This is the only path from an AI suggestion to an active match rule, and it runs only on explicit human approval.

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/rule-suggestions/{suggestionId}/approve" \
  -H "Authorization: Bearer $TOKEN"

{
  "reviewId": "550e8400-e29b-41d4-a716-446655440000",
  "createdRuleId": "550e8400-e29b-41d4-a716-446655440000"
}

Reject a suggestion

Rejecting a PENDING_REVIEW suggestion discards it and creates no rule. The request body is mandatory, but its reason field is optional (send {} to reject without a reason).

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/rule-suggestions/{suggestionId}/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "too aggressive" }'

Matcher records the approving/rejecting principal for audit.

Lifecycle after approval

Once a suggestion is APPROVED, its createdRuleId links to a real match rule that participates in match runs exactly like a hand-authored rule. A review is a one-way state machine: a PENDING_REVIEW suggestion transitions to APPROVED or REJECTED once and cannot be re-decided. Attempting to re-decide, or to approve an already-linked review, returns 409. An approved candidate that fails validation returns 422.

Preview how a candidate rule would behave before you approve it with the read-only simulate endpoint. See Simulation.

Response codes

Status	Meaning
`200`	Suggestions produced, listed, approved, or rejected
`400`	Invalid status filter or suggestion id
`403`	Tenant not opted into rule suggestions
`404`	Rule suggestion not found
`409`	Invalid state transition / already linked
`422`	Approved suggestion failed validation
`503`	Rule suggestion or advisor not available (author rules manually)

Overview

Guides

Matcher UI

MCP Server

Operations

Rule suggestions

Produce suggestions

List suggestions

Approve a suggestion

Reject a suggestion

Lifecycle after approval

Response codes

​Produce suggestions

​List suggestions

​Approve a suggestion

​Reject a suggestion

​Lifecycle after approval

​Response codes

Produce suggestions

List suggestions

Approve a suggestion

Reject a suggestion

Lifecycle after approval

Response codes