---
title: "Produce AI match-rule suggestions (human-review required)"
method: POST
path: "/v1/matching/contexts/{contextId}/rule-suggestions"
tags: ["Matching"]
---

# Produce AI match-rule suggestions (human-review required)

`POST /v1/matching/contexts/{contextId}/rule-suggestions`

Builds AGGREGATE, privacy-safe history features for the context, asks the AI advisor for config-only candidate rules, and enqueues each surviving candidate in a human-review queue. AI output is NEVER authoritative: producing a suggestion CREATES NO rule. A rule is created only when a human APPROVES a suggestion. 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). Tenant from the JWT, context from the path. The egress payload is aggregates only — no raw transaction, money, or PII.

## Path parameters

- `contextId` string, uuid, required — Context ID

## Response `200`

OK

- SuggestRulesResponse
  - `count` integer, required — Number of suggestion reviews produced
  - `items` RuleSuggestionResponse[], nullable, required — Newly created PENDING_REVIEW suggestion reviews; producing them creates no rule
    - `candidate` RuleSuggestionCandidateResponse, required
      - `confidence` number, double, required — Advisor confidence in the suggestion, from 0.0 (lowest) to 1.0 (highest)
      - `config` object, required — Per-type rule configuration over the closed schema; the shape depends on the candidate type
      - `expectedImprovement` string — Advisory note on the expected auto-match-rate effect; never a monetary figure
      - `priority` integer, required — Proposed rule priority in the range 1..1000 (lower runs first)
      - `rationale` string, required — Short human-readable rationale for the suggestion
      - `type` string, required — Proposed rule type from the closed vocabulary: EXACT (strict equality), TOLERANCE (within an amount band), or DATE_LAG (allowing a settlement-date offset)
    - `contextId` string, required — Reconciliation context ID this suggestion belongs to
    - `createdAt` string, required — When the review was created (RFC 3339)
    - `createdRuleId` string — Identifier of the match rule created on approval; empty until an approved review is linked
    - `id` string, required — Unique identifier for the review
    - `rejectReason` string — Optional reason recorded when the suggestion is rejected
    - `reviewerId` string — Principal id of the reviewer; empty until the suggestion is adjudicated
    - `status` string, required — Lifecycle status: PENDING_REVIEW (awaiting human decision), APPROVED (rule created), or REJECTED (discarded)
    - `updatedAt` string, required — When the review was last updated (RFC 3339)
    - `version` integer, required — Optimistic-concurrency version of the review

## Other responses

- `default` — Error

---

[API](https://skmtc.net/lerian/apis/identity-plugin.md) · [All operations](https://skmtc.net/lerian/apis/identity-plugin/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lerian/identity-plugin/versions/25daba385532/schema)