canopy-appeals API Reference

File a fair hearing request (#1098, epic &72 MR 2.1: action-bound filing + the Chart B2 continued-benefits election).

Request: FileAppealRequest

request_date is server-stamped from the gated clock — it left the wire with #1098 (deny_unknown_fields: an old caller still sending it, or adverse_action_effective_date, is rejected loudly). program is the typed snake_case Program vocabulary.

adverse_action_id binds the filing to an enrollment adverse action — when present it is validated hard against enrollment (unknown action, wrong household, or program mismatch is a 422). Omitting it files a narrative grievance: the server cannot know an action exists to demand its id, so the binding requirement is enforced structurally — continued benefits flow ONLY through an action-bound filing (the MR 3.3 worker UI makes action selection mandatory for termination appeals).

Continued benefits (Chart B2, [appeals].continued_benefits_election_days = 14): the election window runs 14 days from the action’s noticed_date — the latest DISPATCHED notice version’s legal notice date served on the enrollment action view (#1164), the SAME date the letter’s printed deadline anchors on, so printed == enforced. Only while no dispatch evidence exists does the constructive fallback apply (enact_not_before − required_advance_days; enact_not_before itself for advance-notice-exempt actions — the pre-dispatch filing path). Continuation is assumed unless waived (Form 118). Outcomes land in cb_election:

Response (201): AppealWithTimeline — includes decision_due_date (60 days from filing per 7 CFR 273.15(c)(1), extendable by recorded postponements) and the CB election block. Errors: 400 (outside the 90-day appeal window), 401, 422 (action binding rejected), 503 (enrollment unavailable for the lookup — retry; the filing date is server-stamped so a same-day retry loses nothing).

List appeals. Filter by household_id.

Query parameters: household_id, limit, offset, and (#1518) optional repeated programs= keys (snake_case Program slugs) — the same contract as the queue’s #1308 filter: ANDed with the other filters, empty/absent = unscoped (additive), unknown slugs → 422. The BFF’s worker appeals index passes the worker’s scope (storage-slug expansion, #733).

Response (200): array of AppealRequest. 422 on an unknown program slug.

List all pending appeals (work queue for hearings officers).

Query (#1308): optional repeated programs= keys (snake_case Program slugs) restrict the queue to those programs — the BFF passes the worker’s primary_programs scope (with the medicaid→{medicaid, chip} storage-slug expansion, #733) so a scoped worker never receives cross-program appeals. Empty/absent = unscoped, jurisdiction-wide (the pre-#1308 contract; additive). Unknown slugs → 422.

Response (200): array of AppealRequest sorted by decision deadline.

Server-side-filtered hearings list for the supervisor dashboard’s Pending Hearings panel (demo-dataset-seed Step 9d). Returns appeals with hearings scheduled within the requested window.

Query parameters: days (days from today, inclusive; defaults to 30, clamped to 1..=365), limit (defaults to 50, clamped to 1..=200), and (#1518) optional repeated programs= keys — same contract as the list/queue filters (empty = unscoped; unknown slugs → 422).

Response (200): array of AppealRequest. 422 on an unknown program slug.

Get an appeal with timeline details (filing date, hearing date, decision due date).

Response (200): AppealWithTimeline. Errors: 401, 404 (appeal not found).

Proxy canopy-snap’s FTI-safe hearing-view for the appeal’s frozen determination (T2-8 #681, ADR-028 §70). Appeals resolves the appeal to its determination + program, then fetches canopy-snap’s service-gated /v1/determinations/{id}/hearing-view with its own service identity — the non-restricted, no-sealed-leaf projection is the only thing that crosses the boundary, and the caller never directly reaches the program endpoint. Service-caller token required (require_service_caller; canopy-web calls it on the worker’s behalf). SNAP-only for now — tanf/medicaid have no replay/hearing-view path yet.

Response (200): HearingDeterminationView. Errors: 401, 403 (caller is not a service), 404 (no such appeal, or the determination has no input snapshot — legacy/pre-ADR-028), 422 (non-SNAP appeal).

Schedule a hearing.

Request: ScheduleHearingRequest

Response (200): AppealRequest. Errors: 401, 404 (appeal not found).

Record the hearing decision (#1099, epic &72 MR 2.2 — Chart B1).

Request: RecordDecisionRequest

decision is the typed vocabulary upheld_agency | reversed_household | dismissed (P12: withdrawn is a LIFECYCLE, not an outcome; pre-#1099 free-text values were migrated or quarantined as legacy_unmapped). Chronology is validated: decision_signed_date ≤ decision_received_date ≤ today, and decision_received_date ≥ request_date — Chart B1’s case-action clock runs from RECEIPT. A dismissal requires a dismissal_basis (7 CFR 273.15(j): abandoned | federal_mass_change | untimely_request); the good-cause flag records a failure-to-appear claim. federal_policy_issue (#1132, default false) types the Chart B3 row-3 fact — the decision determined the issue was federal law/regulation/policy — at decision time (the narrative decision_basis cannot be parsed for it); agency-favorable outcomes only, and a later final appeal never reinstates benefits when set.

Effects, all staged in the SAME transaction as the decision row: timeline event + decision events; for agency-favorable outcomes (upheld_agency/dismissed) with granted CB, the P2 cessation record (initial_decision, dated the NEXT issuance cycle after receipt — first of the following month; the adequate notice, which must NOT advertise another hearing, is rendered by the Phase-3 notices machinery from this record). Then the Chart B1 action command: a reversed_household decision vetoes the bound action (durable, moots every stay); an agency-favorable decision releases this appeal’s stay so the action proceeds next cycle — never an immediate enact. Command receipts persist to cb_stay_link_status + the timeline; refusals are timeline-recorded and failures logged — the receipt/link trail is the input the MR 2.3 reconciliation scanner (next in this phase) sweeps. Both commands are idempotent terminal-state replays on the enrollment side (#1096, pinned by enrollment’s stay-replay tests), so re-recording after a failure is safe.

Response (200): AppealRequest. Errors: 400 (chronology / dismissal fields), 401, 404 (appeal not open).

Record a judicial (final) appeal of the hearing decision (#1132 — Chart B3 / PAMMS Appendix B Final Appeals; HB 790: OSAH decisions appeal only by petition for judicial review in Superior Court).

Request: RecordFinalAppealRequest — { "filed_date": "2026-07-20", "actor": "…", "continue_benefits": true }.

Timeliness: filed_date must fall within [appeals].final_appeal_window_days (30, cited) of decision_received_date — the recorded proxy for service of the initial decision; an untimely filing is refused naming the window. With continue_benefits (Chart B3 row 1), continuation is EXTENDED past the initial-decision cessation: the enrollment stay is re-granted synchronously before anything commits (the 2.1 discipline — never granted-without-stay) via enrollment’s explicit restay command — the initial decision RELEASED this appeal’s link, and the plain stay’s monotonic guard refuses released→stayed by design — then one transaction supersedes the recorded P2 cessation (reason/date/`continued_benefits_end_date back to NULL, the superseded pair audited in the timeline — the window end is unknown until the judicial outcome) and records the filing. If the action enacted before the stay landed, the Chart B2 working-day reinstatement SOP applies from the filing date (cb_reinstate_by persisted). The federal-policy row never reinstates: a decision recorded with federal_policy_issue refuses continue_benefits (the filing itself stays recordable without it). Continuation also requires benefits actually continued pending the initial decision — otherwise there is nothing to continue. The CB assessment worker HOLDS while the judicial review pends (the window end is unrecorded). No events are published — enrollment converges via the synchronous command + the reconciliation scanner, whose lingering-stay predicate exempts a decided appeal with a live extension.

Response (200): AppealRequest. Errors: 400 (untimely / chronology / federal-policy bar / no CB to continue), 401, 404, 409 (already filed / not decided / action dead), 500 (enrollment unavailable — continuation NOT granted; retry).

Record the Superior Court outcome of the final appeal (#1132).

Request: RecordFinalAppealDecisionRequest — { "outcome": "affirmed" | "reversed", "received_date": "2026-09-04", "actor": "…" } (remand is deliberately unmodeled pending SME guidance; the vocabulary is additive).

affirmed with an extended continuation records the P2 final_decision cessation at the next issuance cycle after receipt (the Chart B1 semantics the initial decision uses), re-arms the CB assessment against the extended window (final_decision_cessation trigger; a still-pending item is left alone — it computes against the new cessation), and releases the re-granted stay post-commit. reversed vetoes the adverse action (durable, moots every stay), leaves NO cessation, and re-arms the assessment item so the worker’s reversed arm VOIDS any completed assessment through the one writer path (void + released lines + $0 projection; the downstream claim voids via the staged event) — the household prevailed, so CB received pending review is never recouped.

Response (200): AppealRequest. Errors: 400 (chronology), 401, 404, 409 (no filing / outcome already recorded).

Open the P12 withdrawal lifecycle (#1099 — the empty-body immediate withdraw died).

Request: WithdrawAppealRequest — { "method": "written" | "oral", "actor": "…" }. The pre/post-OSAH-submission stage derives from the hearing-scheduling state. The appeal lands in status = "withdrawal_pending"; an oral pre-submission withdrawal records a written-confirmation due date (request + 10 days). Nothing here touches the enrollment stay — only finalization does.

Response (200): AppealRequest. Errors: 401, 404 (appeal not open).

Record the written confirmation notice for an ORAL PRE-SUBMISSION withdrawal (P12). Server-stamps the notice date; the household’s 10-day reinstatement window runs from it.

Request: ConfirmWithdrawalRequest — { "actor": "…" }. Response (200): AppealRequest. Errors: 401, 404, 409 (not an oral pre-submission withdrawal awaiting confirmation).

The household reinstates the hearing. Allowed while the withdrawal pends and the 10-day window (when started) has not lapsed; the appeal returns to its pre-withdrawal status, the withdrawal audit trail stays on the row, and the stay was never touched.

Request: ReinstateAppealRequest — { "actor": "…" }. Response (200): AppealRequest. Errors: 401, 404, 409 (nothing pending / window lapsed).

Close the withdrawal — the ONLY transition after which the enrollment stay is released (P12). The fenced finalization commits FIRST, optimistically locked against any concurrent transition (enrollment’s link machine is monotonic — a stay once released cannot be re-taken, so releasing before the fence could strand a live appeal without its stay); the release then follows post-commit with its receipt persisted. A release failure leaves only a household-safe lingering stay (it delays the action) — the receipts-vs-links trail the MR 2.3 scanner sweeps. Refused while an oral pre-submission withdrawal’s confirmation notice is unsent or its reinstatement window is open — finalizing early would strip the household’s right.

Request: FinalizeWithdrawalRequest — { "actor": "…" }. Response (200): AppealRequest (status = "withdrawn"). Errors: 401, 404, 409 (nothing pending / window open / confirmation unsent / concurrent transition), 503 (no service identity to release the stay — refused before any commit).

Record THE household-requested postponement extending the 60-day decision SOP (P13, initial-hearings:53; 7 CFR 273.15(c)(4): ONE postponement of up to [appeals].max_postponement_days = 30 days — a second request is a 409). Append-only for audit; the appeal’s decision_due_date moves by days.

Request: RecordPostponementRequest — { "days": 14, "reason": "…", "actor": "…" } (days 1..=30). Response (201): AppealRequest with the extended due date. Errors: 400 (over cap), 401, 404 (appeal not open), 409 (a postponement is already on file).

Run the #1100 reconciliation sweep on demand (service-caller): compares appeals' persisted stay receipts against enrollment’s per-appeal links and flags CB elections parked in pending_stay past [appeals].pending_stay_alert_hours (24). Report-only — remediation lives in the appeals-reconciliation runbook.

Response (200): ReconcileReport — receipts_checked, lingering_checked, findings[] (receipt_link_disagreement | link_missing | lingering_stay — the failed-post-commit residue both sides agree on, caught by a lifecycle-vs-link predicate | pending_stay_past_sla), skipped_unreachable (per-row enrollment outages, counted visibly). Errors: 401, 503 (no service identity).

Internal endpoint — triggers the decision-deadline check (60-day SOP per 7 CFR 273.15(c)(1); #1099 corrected the prior 90-day figure, which was the filing window). Returns counts of approaching and overdue appeals.

Response (200): clock check results. Errors: 401.

Create an IPV referral.

Request: CreateIpvReferralRequest

Response (201): IpvCaseWithTimeline. Errors: 400 (invalid request), 401.

List IPV cases. Filter by person_id.

Query parameters: person_id (required)

Response (200): array of IpvCase.

Get an IPV case with timeline.

Response (200): IpvCaseWithTimeline. Errors: 401, 404 (case not found).

Schedule an Administrative Disqualification Hearing.

Request: ScheduleAdhRequest

Response (200): IpvCase. Errors: 401, 404 (case not found).

Record that the 30-day ADH advance notice has been sent. The system validates that the hearing date is at least 30 days from notice date (7 CFR 273.16(b)).

Response (200): IpvCase. Errors: 400 (30-day notice requirement not met), 401, 404 (case not found).

Record the ADH decision.

Request: RecordAdhDecisionRequest

Response (200): IpvCase. Errors: 400 (invalid decision value), 401, 404 (case not found).

Record a signed waiver (individual admits to IPV without hearing).

Request: RecordWaiverRequest

Response (200): IpvCase. Errors: 401, 404 (case not found).

Impose the disqualification penalty after IPV confirmation. The penalty window (offense number, start/end dates) is derived server-side from the case’s prior IPV count — no request body.

Penalty schedule: 12 months (1st offense), 24 months (2nd), permanent (3rd).

Response (200): IpvCase. Errors: 401, 404 (case not found), 409 (case not in valid status).

Withdraw an IPV case.

Response (200): IpvCase. Errors: 401, 404 (case not found).

Check for active disqualifications for a person.

Query parameters: person_id (required)

Response (200): ActiveDisqualificationResponse — active disqualification details (disqualified flag, end date, program, IPV case ID). Errors: 401.