canopy-eligibility API Reference

Trigger a multi-program eligibility determination.

Since #1471 (ADR-002 Amendment 1 D10): the combined result, the request’s completed flip, and the determination.completed outbox event commit in ONE transaction — no consumer can observe a completion without a persisted combined result. Since #1511 the order ledger’s failed_terminal flip commits atomically with an origin-echoing determination.order_failed event (ids + machine failure_code only — no PII, no upstream prose) on all three terminal paths: the direct terminal settle, the retryable attempts-cap conversion, and the sweep’s stale-claim cap conversion — so an order requester (medicaid CMD) is never left waiting on a clock nobody answers. A synthesized (non-definitive) ProgramResult additionally carries a typed failure classification (unconfigured | breaker_open | transient_upstream | upstream_conflict | terminal_rejection | contract_violation | signature_quarantined | persist_failed, plus the upstream status and a bounded excerpt) so callers branch on the class instead of parsing basis prose; raw upstream error bodies no longer cross the boundary.

Request: (DetermineRequest)

Response (200): (DetermineResponse)

Each entry in programs_approved / programs_denied / programs_pending is a ProgramResult (program, status, optional benefit_amount, optional basis, optional determination_id, optional denial_reason_codes). determination_id is the persisted determination id for a verified outcome — present on approved / denied (and any program-returned pending_verification) results, and absent on synthesised-pending results (unconfigured program, open circuit breaker, signature quarantine, dispatch failure); the canopy-web worker BFF records terminal outcomes back to canopy-applications keyed by it (Plan 4 MR4 / G5). denial_reason_codes is carried for denials (canopy-eligibility does not persist them on the determination row). Determinations with signature_verified: false are quarantined and excluded from the combined result.

Non-persisting dry-run (T2-7, #680; ADR-027 §6). Without target_policy, re-scores a household’s current facts against the frozen policy + pinned corpus of a baseline determination-of-record — the materiality diff the renewals fact-change subscriber consumes. With target_policy (#1472), the same current facts score against the named policy instead — the COLA "preview under October policy" arm the #1213 bulk admin surface composes with. SNAP-only; not worker-facing.

Minimum role: service caller or caseworker-or-above (same gate as POST /v1/eligibility/determine); the downstream canopy-snap calls present canopy-eligibility’s own service token (ADR-019).

Request: (DryRunRequest)

as_of is the evaluation date — for materiality, the triggering change’s effective date (valid_from, Decision J); for a COLA preview, the target cutover date (e.g. 2026-10-01). Facts are read as-of that date (not "today", not the baseline’s as_of). The orchestration: fetch the baseline determination from canopy-snap (verdict + household ownership check); without a target, read its frozen policy_params bundle + corpus_hash from the snapshot; re-fetch the household’s current facts as-of as_of; dispatch the pinned write-free snap dry-run with exactly one policy source. A corpus-less / pre-T2-7 baseline (whose 422s are bundle-extraction failures) still previews under a target — it just can’t replay; a baseline with NO input snapshot at all 422s in either mode (the snapshot supplies the context-faithful application id — structurally dead in real data since #911, kept defensive). Write-free end to end — no eligibility_requests slot, no signature verification, no program_determinations / combined_results persistence, no outbox event.

Response (200): (DryRunResult)

baseline / dry_run are VerdictRef { status, benefit_amount } (unsigned — a dry-run is not a determination of record). In target mode, dry_run is the verdict under the named target and target_policy echoes snap’s full resolution — the requested pins plus the matched parameter set’s intrinsic validity window, i.e. exactly the value a subsequent bulk dispatch passes as expected_policy_target (#1467 pre-write pin). Absent on baseline replay, keeping that wire byte-identical. Errors degrade to manual review, never a 500: a caller without the service/caseworker-or-above role → 403; a cross-household or snapshot-less baseline (any mode), or (baseline replay only) a corpus-less / pre-T2-7 incomplete frozen policy bundle → 422; an unknown pinned corpus, or a target params_digest matching no loaded snap parameter set → 422; an unknown baseline determination → 404; a household with no members → 400.

Get an eligibility request by ID.

Response (200): EligibilityRequest. Returns 404 when the request ID is unknown.

Get all program determinations for an eligibility request.

Response (200): array of ProgramDetermination. Since #1479 each row also exposes the #1467 policy provenance: policy_target (corpus hash
params digest + effective period — bulk rows stamped per #1213, interactive rows from the signed envelope as it arrived) and evaluated_as_of (the envelope’s evaluation date). null when no attestation arrived (pre-#1467 rows, emitters with attestation off; evaluated_as_of is also null on bulk-adopted rows, which the read view cannot attest).

Get the combined result for an application.

Response (200): CombinedResult. Returns 404 when no combined result has been assembled for the application.

The worker-SCOPED alerts feed (#596, PUB-1075 AC-6 least privilege). Rows derive from program_determinations (statuses: denied, sanctioned, time_limit_exceeded, disqualified, terminated, abawd_exceeded; provenance-quarantined rows — signature_verified = false — never surface) and are filtered to households the effective worker holds an ACTIVE household_assignments row for, looked up live from canopy-applications per request. Scope-THEN-limit: the household predicate applies before the top-N, so a small caseload is never starved by jurisdiction noise. Accepts ?limit={n} (clamped [1, 50], default 10 — a bounded triage feed, deliberately not a keyset page) and (#1518) optional repeated programs= keys (snake_case Program slugs; empty = unscoped, unknown slugs → 422) — the BFF passes the worker’s program scope, an axis ORTHOGONAL to the assignment filter.

Authorization (the effective worker is the path param):

Fail-closed: canopy-applications unreachable (or the lookup blowing its 3s absolute deadline, or an assignment set past the 5,000 cap) is a coded 502 (applications_unreachable / assignment_set_too_large) — NEVER the unscoped list, with no deployment override (per the ratified \#596 spec). A consecutive-failure breaker (5 → open 30s) keeps BFF retries from amplifying an applications outage. A worker with zero assignments receives []. Each read publishes the aggregate eligibility.cross_program_alerts.accessed audit event (ids only).

Response (200): array of CrossProgramAlert.

The UNSCOPED jurisdiction-wide alerts feed (#596): supervisor/admin triage tooling, plus the allowlisted canopy-web service caller rendering supervisor dashboards. Never consults assignments — supervisor triage survives a canopy-applications outage. Accepts ?limit={n} (clamped [1, 50], default 10) and (#1518) optional repeated programs= keys (same contract as the scoped feed) — the supervisor’s dashboard panel passes their claim’s programs, so "unscoped" here means assignment-unscoped, not program-unscoped.

The pre-#596 GET /v1/eligibility/cross-program-alerts path is RETIRED (404, no alias): old replicas 404 the new paths and new replicas 404 the old one, so mixed deployments fail closed in both directions.

Response (200): array of CrossProgramAlert. 403 when the caller is neither supervisor-or-above nor the allowlisted service.

Latest determination for a single household, used by the case-search status badge. Accepts ?household_id={hid}. Returns 404 when the household has no determination yet (the badge falls back to "Pending").

Response (200): CaseStatus. Returns 404 when the household has no determination yet.

Minimum role: dual-or-portal (#1441: service, caseworker-or-above worker, or the scoped portal credential on portal:determinations:read; since #1442 the portal arm also requires the signed ownership claim binding the queried household — the portal home page’s coupling, see the authorization inventory).

Every program determination for a household, newest first. Powers the canopy-web case-detail identity hero + Determination tab so a single round-trip lights up active benefits across all programs without fanning out across per-program services. Accepts ?household_id={hid}.

Response (200): array of ProgramDetermination.