canopy-renewals API Reference

Create a certification period.

Request:

certification_type is the caller-DECLARED MT-87 category (#956 — the server persists it verbatim and never infers it from the period length): standard (6 months), elderly_disabled (12 months, no earned income), senior (36 months), abawd (4 months) per PAMMS 3105 Chart 3105.1. An out-of-vocabulary value is refused at deserialization (422). The interim-contact due date is server-derived (declared standard type only); it is not a request field.

Response (201): SnapCertification object.

Get the active certification for a household.

Query parameters: household_id (required)

Get a certification by ID.

List active certifications, keyset-paginated (#1204). Two scopes share this endpoint:

Query parameters:

Response (200): a SnapCertificationPage envelope — items (this page’s SnapCertification rows), next_cursor ({after_end_date, after_id}, present only when the page was exactly limit rows), and total_in_scope (the authoritative COUNT(*) of the requested scope, populated only on the first page). There is no unbounded single-array mode: at GA caseload scale the old ?days=1464 full-caseload dump (~450–500MB) could not survive the reporting client’s 30s whole-body timeout (#1204, scale audit C2). canopy-reporting page-loops the active_on scope to exhaustion and asserts extracted == total_in_scope (fail-closed completeness tripwire, #1042).

Freeze an immutable federal-universe snapshot generation (#1470; ADR-002 Amendment 1 D5 — the #1213 bulk-cohort source). Materializes, server-side in ONE transaction (one MVCC snapshot), every certification in force on active_on (same scope predicate as GET /snap/due?active_on=), then commits the authoritative row_count with the rows. Unlike a paged scan of the live table, the frozen generation is immune to churn: paging its rows to exhaustion returns exactly row_count members, always.

Minimum role: service-caller

Request: { "active_on": "2026-10-01" }

Response (201): UniverseSnapshot — { id, active_on, row_count, created_at }.

Keyset page over a frozen generation (#1470). Rows carry { seq, certification_period_id, household_id, application_id, determination_id } — determination_id is the certification’s establishing determination, the supersession baseline the bulk core stamps per case. seq is dense 1..row_count, so ?after=<seq> paging can neither skip nor duplicate a member. 404 for an unknown generation (never an empty page). Generations are reaped after CANOPY_RENEWALS__UNIVERSE_SNAPSHOT_RETENTION_DAYS (default 30).

Minimum role: service-caller

Response (200): UniverseSnapshotRowsPage — items + next_cursor (absent on the final page).

List certifications with overdue interim contacts.

Query parameters: as_of (optional, ADR-033 tier-2 override) — anchor date for the scan, defaulting to the gated clock’s today when omitted.

Cross-program "Overdue cases" panel feed (#520). Phase 1 returns SNAP rows whose certification has expired but is still flagged active — the actionable cases for a worker right now. TANF / Medicaid / CAPS / WIC need per-program due-date endpoints before they can join the aggregator (Phase 2 follow-up); the panel wire shape (program field) survives unchanged.

Query parameters: as_of (optional, ADR-033 tier-2 override) — anchor date for the overdue scan (and the days_overdue arithmetic), defaulting to the gated clock’s today when omitted.

Response (200): array of OverdueCase objects. Each row carries household_id, program, action_type (distinguishes "renewal certification expired" from "interim contact overdue"), due_date, and days_overdue — render-ready for the worker portal panel.

Supervisor/analyst dashboard caseload-depth trend (#702). Returns the count of distinct households whose SNAP certification was in force at the close of each day/week bucket over the look-back window, zero-filled so the series is continuous within materialized coverage (a bucket with no active certs reads count: 0, never omitted). Service-caller only (ADR-019).

Since #1218 (scale audit H11) the series is served from the snap_caseload_daily rollup — render cost is O(buckets), independent of caseload size (the pre-#1218 per-render 12-bucket × whole-caseload aggregate exceeded the panel’s 5s budget at GA scale, and each Retry stacked another). The semantics are unchanged: the rollup is the SAME lossless interval reconstruction (a cert counts at bucket-end W iff certification_start_date ⇐ W ⇐ certification_end_date and terminated_at is null or after W; COUNT(DISTINCT household_id) dedups recertification overlap), materialized daily over the full serving window ([anchor−735d, anchor+8d]) by the canopy-renewals.caseload-rollup window-fenced job — so retroactive mutations (a Chart 3730.1 reopen clearing terminated_at, a backdated certification insert) self-heal within the freshness contract. One clock governs everything: the handler’s single gated-clock reading bounds the window, ends the series spine, and anchors the freshness check.

Honest 503 contract: absent coverage (first boot before the immediate probe materializes; coverage-exceeding eval dates after a long scheduler outage) or a generation older than 48 whole hours returns 503 Service Unavailable + Retry-After: 60 — never a fabricated zero-series ("caseload collapsed") and never a beyond-contract stale 200. The tail bucket is at most ~24h stale in normal operation; POST /v1/renewals/caseload-rollup/refresh (below) refreshes on demand.

Query params: window (<n>d / <n>w, default 12w, clamped ≤ 366 days / ≤ 104 weeks), bucket (day | week, default week; any other value → 422), program (snap only in this slice; any other value → 422).

Response (200): CaseloadTrend — { buckets: [{ bucket_start, count }], bucket }, oldest bucket first. (503): RFC 9457 problem body + Retry-After.

Honest scope: standard SNAP certification depth only. It excludes Transitional SNAP (snap_tsnap_certifications, owned by canopy-snap) and all non-SNAP programs; the cross-program roll-up is the deferred canopy-reporting HTTP-aggregation (#728, ADR-001). It is not application inflow (that is canopy-applications' distinct GET /v1/applications/caseload-trend, #718).

Recompute the snap_caseload_daily serving window NOW (#1218 R4) — the manual twin of the daily fenced job, for operators (e.g. after a mass reinstate), journeys, and tests (devstack seeds land after boot). Service-caller only; deliberately NO caller-supplied date (a trigger mutates; scan dates are never a caller knob). Runs under the rollup job’s advisory lock and, on success, consumes today’s fence window so the background probe doesn’t repeat the sweep. ADR-007 CLI parity: canopy renewal caseload-rollup-refresh.

Response (200): { skipped: false, rows_refreshed } — the refresh ran (rows = the full coverage width). (202): { skipped: true, rows_refreshed: null } — another caller held the advisory lock; a refresh is running elsewhere.

Record an interim contact.

Request:

Contact methods: phone, mail, in_person.

Regulatory basis: 7 CFR 273.12(a)(1)(ii) — interim contact at certification midpoint.

Record a change in circumstances during certification.

Request:

Change types: income_change, household_change. If reported income exceeds the 130% FPL gross income limit (loaded from rules engine), the case is flagged for redetermination.

List the recert nudges the materiality subscriber recorded for a household, newest first. Backs the case-detail renewals section (canopy-web) and canopy renewals nudge list.

Query params: household_id (required, UUID); pending_only (optional, default false) — when true, returns only the material, not-yet-actioned nudges (the actionable worker queue).

Returns 200 with an array of RecertNudge (id, certification_id, household_id, source_person_id, triggering_fact_kind, baseline_status/baseline_benefit_cents, dry_run_status/dry_run_benefit_cents, benefit_delta_cents, is_material, action_taken/action_by/action_at, created_at).

Record a worker’s file-recert / dismiss decision on a pending material nudge. Backs the case-detail file-recert / dismiss buttons (via the canopy-web /actions/renewals/* handlers) and canopy renewals nudge action.

Request:

action ∈ filed_recert | dismissed; action_by is the acting worker’s subject UUID (forwarded by the BFF — the endpoint is service-caller-gated). The update is guarded WHERE is_material AND action_taken IS NULL, so an unknown id, an immaterial nudge, or an already-actioned one all return 404 (a re-action is a no-op — the first decision stands). Returns 200 with the updated RecertNudge. Filing records the worker’s intent only; provisioning the recert application is a tracked follow-up.

List a household’s cycles, oldest due month first.

Query parameters: household_id (required, UUID).

Response (200): array of SnapPeriodicReport.

Fetch one cycle. 404 if unknown.

Record form receipt (3730 Step 2). complete: false is the worker’s "No" on the Periodic Report Details page — a form not completed in its entirety is NOT filed (3730:35), the cycle moves to form_incomplete, and it stays eligible for the 5th-of-month combined notice. complete: true moves it to form_complete; a complete form can never be un-filed (later complete: false → 409).

Request:

form_kind must be in the jurisdiction’s [snap.periodic_reporting] accepted_form_kinds vocabulary (["528", "297", "508"] for Georgia — 3730:110-117; anything else → 422 naming the configured list; #1165). Legal from scheduled / notice_sent / form_incomplete.

Record a verification checklist sent (3730 Step 4, driven by reported changes per 3730:43-52 or discrepancies per 3730:56). The sent date is server-stamped; due_date defaults to sent + vcl_response_days and anything allowing fewer than 10 calendar days is 422 (3730:218; a DB CHECK backstops it). Legal only from form_complete — verification is decided after a complete form is examined (3730:41).

Request:

reason ∈ reported_change | discrepancy.

Record that all required verification arrived and discrepancies are resolved (3730 Step 4 → 5). Legal only from vcl_pending. No body.

Process the cycle (3730 Step 5) in ONE locked transaction: the certification row lock (serializes against recertification), the processed stamp, one change-report row per reported change (the 130%-FPL redetermination flag decided in the INSERT), and the renewal.snap_periodic_report_processed outbox event commit or roll back together. Legal from form_complete (no verification required, 3730:41) or verified. Changes recorded here are effective the first month of the new reporting period (3730:62); completion does NOT assign a new certification period (3730:161, :69-70). An empty changes list is the no-changes path.

Request:

Response (200): the processed cycle. 409 when the cycle is not completable or its certification is no longer active (a superseding recertification cancels open cycles in its own transaction — the late completion loses cleanly).

Reopen a TERMINATED cycle when the missing form/verification arrives within 30 days after the due month (#1108, epic &72 MR 5.3 — Chart 3730.1 rows 4/5). Cross-service in converge-on-retry order: validate → canopy-enrollment’s idempotent per-action reopen (POST /v1/adverse-actions/{id}/reopen — un-terminates the enrollment, bumps lifecycle_revision, records the receipt) → one local tx under the certification lock (cycle rejoins the state machine, certification reinstates terminated → active with terminated_at cleared). A crash between the enrollment call and the local tx converges when the SAME request is retried (the cycle is still terminated, the enrollment replay no-ops); a retry with a DIFFERENT received_date is refused 409 naming the recorded date — the enrollment’s stored receipt is the proration anchor and a divergent local stamp would silently split them.

The ARM is derived from the row, never claimed: a cycle that reached the VCL (vcl_sent_date set) died on verification — the receipt is the VERIFICATION (row 4; cycle → verified; SOP = receipt + reopen_verification_sop_workdays workdays; form_kind must be omitted, 422 otherwise); any other terminated cycle is a nonfiler — the receipt IS the form (row 5; cycle → form_complete; SOP = receipt + reopen_late_filing_sop_days calendar days, expedited N/A; form_kind required, from the same accepted_form_kinds vocabulary, and complete per 3730:35). reopened_date/sop_due_date stamp the row; terminated_date survives as history. Benefits prorate from the receipt date on the enrollment side (the receipt-month issuance uses the anchor; missed intervening months are NOT restored — #1113); processing then flows through the NORMAL VCL/verify/complete machinery, whose completion event finds the enacted action already reopened and leaves it untouched.

Request:

Response (200): the reopened cycle. 400 — receipt in the future or before the due month. 409 — cycle not terminated, the window elapsed (receipt > due-month-end + reopen_window_days → re-application), canopy-enrollment refused (not enacted / successor enrollment / wrong source), or the household re-applied (the one-active-cert partial unique refuses the reinstate). 422 — arm-inconsistent form_kind.

Query parameters: household_id (required), pending_only (default false — true narrows to the actionable queue).

Response (200): array of PrRedetermination (certification_id, periodic_report_id, generation, adverse_action_id, trigger_kind ∈ action_vetoed/action_cancelled, action_taken/action_by/action_at).

Request: { "action": "redetermined" | "dismissed", "action_by": "<worker uuid>" } — guarded WHERE action_taken IS NULL; a double-submit, unknown id, or already-actioned entry collapses to 404 (the recert-nudge shape). Recording redetermined captures intent only, like the nudge filed_recert.

Run one daily-check pass NOW — the renewals face of enrollment’s enact-sweep trigger (#1102). One pass = cycle materialization (#1106) + the two 3730 drains below + the due-list gauges, every stage drained to exhaustion in keyset pages within the CANOPY_RENEWALS__PR_TICK_BUDGET_SECS time budget (#1210 — the pre-#1210 pass capped each stage at one 500-row page), under the scheduler’s advisory lock (the background loop — hourly probes under the #1211 once-per-UTC-day window fence — and this trigger serialize; 202 + skipped: true when another replica holds it, 200 + the SchedulerCheckView counters when this call ran the pass). Gauges are true COUNT(*) magnitudes, and the materializer’s tombstones discriminate calendar_elapsed_at_cutover (due month already gone when the pipeline first ran) from materializer_behind (pr_cycles_missed_behind — the pipeline’s own lateness, ERROR-logged). Runs on the service’s gated clock — deliberately NO caller-supplied date on the wire: a trigger MUTATES, so scan dates are never a caller knob (ADR-033 tier-2 as_of is a read-path affordance). Journeys pair this with the /test/clock fleet advance (interval loops do not re-fire on a logical advance). Service-caller only.

Minimum role: service-class caller.

Request:

Response (201): the inserted SnapChangeReport row (table reused; program column discriminates).

Minimum role: service-class caller.

Request:

Response (201): the inserted SnapChangeReport row.

Worker-portal MyQueue per-program due feed (plan: worker-intake-program-independence MR3). Accepts any canopy_reference::Program slug. Phase 1 returns the SNAP page when program=snap (same data + keyset envelope as /v1/renewals/snap/due) and an empty, complete page (items: [], next_cursor: null, total_in_scope: 0) for every other program — those services don’t yet expose per-program due-date stores. Returns 422 for unknown program slugs so a typo surfaces rather than silently empty-resulting.

Query parameters: same keyset + scope params as GET /v1/renewals/snap/due (limit, after_end_date, after_id, days, as_of, active_on).

Response (200): a SnapCertificationPage envelope (see GET /v1/renewals/snap/due).

Minimum role: caseworker.

Response (200): array of SnapCertification objects.

Response (422): unknown program slug.