canopy-medicaid API Reference

Run a Medicaid/CHIP eligibility determination. Called by canopy-eligibility orchestrator.

Minimum role: service-or-exchanged (#1426): the orchestrator’s service token, or an exchanged user-context token (aud=canopy-medicaid exactly, allowlisted azp, caseworker-or-above role). FTI access attribution (accessed_by) resolves via EffectiveUser.

Request: ApplicationContext carrying a members[] list. Medicaid is multi-subject (ADR-035): the handler runs the cascade per member, scoring each on that member’s own age + disability; an empty members[] falls back to a single applicant determination. Income stays household-level (per-member budget-group composition is deferred to #864).

The handler, per member:

All N per-member determinations + their COA-evaluation rows + their input snapshots + the per-member FTI chain entries persist in one transaction (all-or-nothing). An invalid or duplicate member person_id returns 422.

Bearer token is forwarded per-call (no shared RwLock race condition).

SSA SOLQ input (#384): the orchestrator may populate ApplicationContext.ssa_solq: Option<HashMap<Uuid, SolqRecord>> pre-dispatch for elderly / disabled applicants. When present, derive_abd_flags_from_solq(map, applicant_id) projects the SSA record onto the five Phase D booleans (lost_ssi_due_to_cola, is_disabled_adult_child, is_disabled_widow, is_widow_60_64, lost_ssi_as_disabled_child) consumed by the medicaid-non-magi ruleset. The pre-existing Option<bool> ApplicationContext fields stay as an override channel (test fixtures, manual worker overrides) and win when present; SOLQ derivation is the implicit default. When SOLQ is unconfigured or returns no record, all five flags fall back to false — exact match for the pre-#384 behaviour. Per ADR-004, raw SOLQ records are stored only in this service’s database and are never re-emitted to the orchestrator. As of T2-3 (#684) the raw record is additionally frozen by value into the determination snapshot’s cross_program_inputs.solq (still DB-local, never on the wire), so the verdict reproduces even if the SOLQ→flag derivation later changes.

Response (200): DeterminationList — one signed SignableDetermination envelope per member (ADR-035), each carrying its person_id; per ADR-002 (selected COA in program_extension, status, basis, benefit fields, JWS signature, and the snapshot_hash binding that member’s input snapshot per ADR-028). The orchestrator verifies each signature against this same shape and receives only outcome + hash, never the snapshot cleartext (which stays inside canopy-medicaid’s Pub 1075 boundary); the per-program MedicaidDeterminationRead rows are what the read endpoints below return.

Response (503, dormant until #1279): when the chain-v2 FTI append arm is enabled (CANOPY_MEDICAID__CHAIN_V2_APPEND_ENABLED, #1207 / ADR-014 Amendment 7) and the append hits an Environment-class refusal — topology missing, epoch not active/current, routing-version skew, or a malformed source registry — the whole multi-member determination aborts fail-closed (no Pub 1075 snapshot can persist without its chain row) with the fixed detail audit chain unavailable; the environment specifics go to logs only. With the flag off (the default), this arm is unreachable.

List determinations newest-first, keyset-paginated (#1195).

Minimum role: caseworker.

Query parameters: limit (default 50, max 200), after_determined_at + after_id (keyset cursor — pass the previous page’s next_cursor fields together; omit both for the first page), month (optional, any day in the month).

The list is ordered (determined_at DESC, id DESC) — newest first, with the UUID-v7 id as a stable tiebreak — and keyset-paginated over that compound cursor (there is no offset; the old hard LIMIT 200 cap that silently truncated the T-MSIS federal universe is gone; the previously-documented household_id/person_id filters were never honored by the handler and are not part of the contract — cross-program callers filter client-side). The default page rides idx_medicaid_determinations_determined_at_id, an index scan with no top-N sort. month scopes the universe to determinations whose coverage window [effective_date, expiration_date] overlaps that calendar month (the T-MSIS monthly-eligibility universe); when set, the first page carries total_in_scope (the authoritative scoped COUNT(*)) so a page-looping extractor can assert completeness. The month scope is service-caller-only (#1249, ADR-001 Amendment 1 least privilege): the completeness universe belongs to the reporting extractor — an interactive caller gets 403 and uses the unscoped list.

Response (200): MedicaidDeterminationPage — items (array of MedicaidDeterminationRead, each the MedicaidDetermination fields flattened including the required snapshot_hash) + next_cursor ({after_determined_at, after_id} while a full page may have more; null at the end) + total_in_scope (first page of a month-scoped query only; null otherwise).

Fetch a determination by ID.

Minimum role: caseworker.

Response (200): MedicaidDeterminationRead — the MedicaidDetermination fields flattened, including the required snapshot_hash (#911: legacy pre-snapshot rows were deleted and the ADR-028 §58 snapshot_status marker retired). Returns 404 if no determination exists for the supplied ID.

List every COA evaluated for the Medicaid application — both eligible and ineligible. Each row includes the rule-trace pointer used (which ruleset, which version) so caseworkers can answer "why this COA, why not that one." Source-of-truth for hearings. The {id} is the medicaid_application_id (#1011 moved this from /determinations/{id}/categories, where the URL implied a determination id but the handler keyed on the application id — a natural-reading caller silently got an empty list).

Minimum role: caseworker.

Human-readable explanation of the determination — selected COA, basis, thresholds compared. Useful for case notes and notice generation.

Minimum role: caseworker.

Crypto-shred a determination’s frozen input snapshot (T2-6 #687, ADR-036). The per-determination DEK in redaction_keys is tombstoned (its wrapped_dek overwritten with a zero sentinel + shredded_at stamped), so every sealed leaf becomes permanently unrecoverable, while the snapshot ciphertext and the signed snapshot_hash are left untouched — the snapshot still re-hashes to the signed value and the determination’s JWS stays verifiable (hash-over-ciphertext, ADR-036 Decision B). Only the plaintext PII is destroyed. Medicaid is FTI-bearing, so the determination.redacted event is plaintext-free (IDs + actor + reason only, ADR-004).

Minimum role: data_steward only — a dedicated, privileged, irreversible role for redaction/expungement. Admins do NOT auto-hold it (separation of duties, mirroring fti_auditor). A require_user_only route (#1426): service-class bearers are always 403; under enforce_user_only_routes the bearer must be an exchanged per-target token carrying the role.

Request:

reason is mandatory; a blank reason is rejected with HTTP 400.

The shred and a plaintext-free determination.redacted audit event (carrying the steward’s sub + the reason) commit in one transaction (ADR-018); canopy-security audits it via the existing wildcard subscriber.

Response (200): { "determination_id": "…​", "redacted_at": "…​" }. Returns 400 on a blank reason, 403 if the caller lacks the data_steward role, and 404 for an unknown determination. Idempotent: re-redacting an already-shredded determination tombstones 0 rows and still returns 200.

The path uses the sub-resource form …/{id}/redact (mirroring snap’s reference impl), not the AIP-136 custom-method …/{id}:redact — axum/matchit 0.8 allows only one parameter per path segment.

List Transitional Medicaid (TMA) coverage records. Created by the tanf.case_closed subscriber per 42 USC 1396r-6 / PAMMS 2166. Phase 1 (no income test) / Phase 2 (205% FPL with quarterly reporting).

Minimum role: caseworker.

Query parameters: household_id, person_id.

List Express Lane Eligibility evaluations. Created by the snap.application_approved / tanf.application_approved subscribers per 42 CFR 435.1102 — child enrollment in Medicaid via cross-program findings.

Minimum role: caseworker.

Query parameters: household_id.

List FTI audit entries. IRS auditor access only.

Minimum role: fti_auditor (dedicated role; admins do NOT auto-hold it). A require_user_only route (#1426): service-class bearers are always 403; under enforce_user_only_routes only an exchanged per-target token carrying the role passes.

Query parameters: from, to, actor_id, event_type, limit, offset.

Fetch a single entry (full event payload).

Minimum role: fti_auditor — same require_user_only posture as the list route.

Aggregated counts by event type + actor over a date range. Used by Pub 1075 §9 quarterly review.

Minimum role: fti_auditor — same require_user_only posture as the list route.

File an overpayment claim.

Minimum role: caseworker (or service-class token).

Request:

claim_basis ∈ agency_error / inadvertent_household_error / ipv. claim_amount_cents > 0.

Response 201: the persisted OverpaymentClaim row.

One keyset page of claims WITH server-side ledger totals (#1222) — same envelope and semantics as the canopy-snap page (see the SNAP API page); the three services stay byte-identical.

status ∈ open / in_repayment / closed / written_off.

Read a single claim.

Attach a repayment plan. HTTP 409 if claim is closed or written_off.

Append a recoupment ledger entry. Same TX semantics as canopy-snap and canopy-tanf.

Full ledger view + derived total_recouped_cents + outstanding_cents.

Guard: ADR-043 receiver contract — service class OR an exchanged worker bearer (caseworker+); attribution is the verified EffectiveUser identity, never a request field.

Request:

cmd_event_type is the closed canopy_reference::CmdEventType vocabulary.

Response (202): the lifecycle handle (state, deadline_at, processed_at = null until settled). The response is a handle, not an outcome — poll GET /v1/cmd/events.

The household’s CMD lifecycle rows, newest first (bounded at the 100 most recent). Guard: service class or exchanged caseworker+. Backs the worker portal’s determination-tab status table.

The cross-household escalation feed (#1511): unresolved rows whose PAMMS 2750 deadline is inside the [medicaid].cmd_escalation_warning_days window (overdue included) plus state='failed' rows, most-urgent deadline first, bounded at 50. Guard: service class or exchanged caseworker+. Backs the worker-dashboard CMD-escalations panel — the worker-visible arm of the 10-day clock. Both clock values are jurisdiction data since #1511: [medicaid].cmd_clock_days stamps deadline_at at ingest (previously a '10 days' SQL literal) and cmd_escalation_warning_days bounds this feed (mirrors the [appeals] clock-pair precedent, ADR-003).

Events: medicaid.cmd_cascade_completed (per-subject cascade telemetry, #1505 wiring), the determination.requested::Order publication above, and — consumed, not published — determination.order_failed (canopy-medicaid.cmd-fail): a terminal order failure marks the CMD row state='failed' + failure_code, surfacing it on the escalation feed. Metrics: canopy_medicaid_cmd_unresolved_depth / _oldest_unresolved_age_seconds (alerting threshold = cmd_escalation_warning_days before the deadline); _terminal_failed is LIVE since #1511 (counts state='failed' rows).

Operator action for resolving a signature-quarantine quarantined determination. Sets medicaid_determinations.status to requeued (action=requeue) or dismissed (action=dismiss). Unknown actions return 400.

Minimum role: service-class caller.

Request:

Response (200): { "determination_id": "uuid", "resolution_action": "requeue", "new_status": "requeued" }.