Skip to main content
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; a rule is created only when a human approves a suggestion. This guide covers the human-in-the-loop (HITL) rule-suggestion queue.
The lane is gated by a global advisor kill-switch and a per-tenant opt-in (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": { "tolerance": 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 are drawn 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 — nothing is created. The body is optional. 
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" }'
The approving/rejecting principal is recorded 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

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