canopy-applications API Reference

Create a new application. Atomic — the applications row, all application_programs rows, and any expedited screening result commit in a single transaction (regression covered by create_with_three_programs_and_expedited_is_atomic; see #314).

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

Request:

programs_requested is validated against canopy_reference::Program (snake_case strum) — invalid values return HTTP 422 with every bad value listed (#399).

Response (201): ApplicationWithPrograms — the application row plus per-program rows with deadlines.

List applications. Empty filter returns the most recent 50 rows ordered by received_at desc.

Minimum role: caseworker.

Query parameters (#402):

Plural programs[] / statuses[] are parsed via axum_extra::extract::Query (the stock axum::extract::Query collapses repeated keys to the last value). Filters combine with AND. The program filter uses an EXISTS join against application_programs.active = true; the partial indexes added in 20260510000000_add_list_filter_indexes.sql keep this index-only at scale.

Response (200): array of Application.

Get the COMPACT reporting core for a set of applications in one round-trip (#1203, D5 row 2) — one id = ANY($1) primary-key probe replacing the federal extracts' per-case application GET N+1. Capped at 500 IDs per request (422 on overflow); duplicates collapse to one entry; the response follows first-occurrence request order. Service callers only (§B4 bulk-read posture) — 403 for worker JWTs.

ApplicationCore is deliberately NOT ApplicationWithPrograms: no program rows, no interview/waiver detail, no confidentiality — exactly the fields the extract folds read, so a 500-application response stays bounded under the 2MiB idempotency-replay cache.

Absent semantics: a missing or inactive (withdrawn/soft-deleted) application is simply ABSENT from the result — consumers diff the requested id set (the reporting fold counts each absence in its cert_type_unknown bucket, #1155). expedited_eligible is null when the application was never expedited-screened — counted expedited_unknown downstream, never a fabricated false.

Request: BatchGetApplicationsRequest

Response (200): Vec<ApplicationCore> — [{ id, household_id, status, expedited_eligible, received_at }].

Application-inflow time-series for the supervisor/analyst dashboard trend sparkline (#718). Counts applications.received_at into day or week buckets over a look-back window, zero-filled via generate_series so the series is continuous (a bucket with no inflow is count: 0, never omitted). This is the operational caseload feed; it is owned by canopy-applications (the holder of received_at), distinct from the federal reporting surfaces in canopy-reporting.

It measures application inflow over time (the workload arriving) — not open-queue-depth over time, which would require point-in-time caseload snapshots that do not exist yet.

Minimum role: caseworker (service-caller).

Query parameters:

The day/week granularity is chosen by matching the validated bucket against a closed set, so no caller input is interpolated into the date_trunc SQL. No migration — the query is a GROUP BY date_trunc(…​) read over the existing received_at index.

Response (200): CaseloadTrend — { buckets: [{ bucket_start, count }], bucket }, oldest bucket first.

Get an application with its per-program rows.

Minimum role: service-class, or the scoped portal credential (portal:applications:read, #1441; since #1442 the portal arm also requires the signed ownership claim binding this application) — there is no direct worker arm on this route.

Response (200): ApplicationWithPrograms.

Update application metadata. Only submission_channel, authorized_representative_id, and programs_requested can be changed (the latter via the same transactional sync used at intake — #400).

Minimum role: caseworker.

Request:

When programs_requested is present it’s the complete desired set: programs already on the application stay (preserving processing_deadline, expedited, tanf_service_type); programs in the list but not on the application get a fresh row with a freshly-computed deadline; programs on the application but not in the list are soft-deleted (active = false — history row retained for audit). Same #399 validation applies — invalid program codes return 422.

Response (200): ApplicationWithPrograms post-update.

Withdraw an application (soft-delete: active = false, status = "withdrawn").

Minimum role: caseworker.

Waive the interview requirement.

Minimum role: caseworker.

Request:

Valid reasons: elderly_disabled, hardship, homebound.

Mark the interview as completed (stamps interview_completed_at).

Minimum role: caseworker.

Record a program-level determination result on the application. Called by the canopy-web worker BFF after a POST /v1/eligibility/determine succeeds (the orchestrator returns the per-program determination_id in the DetermineResponse); not called directly by humans.

Minimum role: service-class token.

Request:

status ∈ approved / denied / pending. denial_reason_codes required when status = "denied".

Writing the per-program row and recomputing the parent applications.status happen in one transaction (Plan 4 MR4 / G5): when every active application_programs row is terminal (determined / approved / denied / withdrawn) the application flips to determined, which drops it from the worker queue (GET /v1/applications?statuses=submitted&statuses=processing); the first non-pending program moves a submitted application to processing. 404 if no active application_programs row matches {program}.

List the active intake sections for an application.

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

Response (200): array of ApplicationSection. Returns 404 if the application is unknown.

Upsert a typed-per-section JSON payload for one (program, section) pair. The body payload is validated against the matching per-section struct at write time; the stored DTO surfaces it as JSON. last_edited_by records the worker’s Keycloak sub (not FK’d — workers are not persisted in canopy-persons).

Minimum role: caseworker (or service-class token). The bearer must be service-class or caseworker-or-above; otherwise 403.

Request: typed-per-section JSON payload (shape varies by section). The three SNAP verification sections (income_employment, resources, expenses_shelter) carry a verifications array that is min = 0 and serde(default) — a caller may omit it entirely and it deserializes to [] (a no-income / categorically-eligible / homeless household legitimately collects none). household_composition requires a members array of at least one { person_id, relationship_to_head, … } ref; the worker-portal BFF synthesizes this from the canopy-persons household membership rather than asking the worker to re-type it.

Response (200): the upserted ApplicationSection. 401 when the bearer is missing/invalid or lacks sub; 403 when the bearer is neither service-class nor caseworker-or-above; 422 for an unknown section, a program not on the application, a section not applicable to the program, or a payload that fails validation.

Gate that marks a program’s data collection complete. On success it returns the updated ApplicationProgram row plus the recomputed container applications.status string. On gate failure it returns 422 with the list of missing section slugs instead.

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

Response (200): CompleteDataCollectionResponse — { "application_program": ApplicationProgram, "applications_status": "…" }. 404 if the application is unknown or the program is not active on this application; 422 if one or more applicable sections lack a completed_at.

Verify an HH-[a-f0-9]{8} Application ID code + a 12-digit passcode (NNNN-NNNN-NNNN).

Minimum role: the portal’s citizen-class credential only, since #1441 (azp allowlist + portal:intake scope — the applicant authenticates through the portal; there is no applicant bearer yet). Any other principal, service class included, returns 403 portal_only_route.

Request:

The passcode is normalised (dashes + whitespace stripped) before verification, so IVR-keypad / read-aloud entry without the cosmetic dashes succeeds. Verification requires an active (revoked_at IS NULL) passcode_hashes row — a rotated/revoked passcode never authenticates even though its row persists for audit.

Response (200): VerifyCredentialResponse — { "application_id": "uuid" }. The reserved id may belong to an in-flight draft (no applications row yet, per the ADR-026 reserved-id lifecycle) or a submitted application.

401 — returned for both an unknown code and a wrong (or malformed) passcode, with an identical status + body (the standard RFC 9457 problem response): the endpoint is deliberately not a credential oracle, and the store layer equalises argon2 verify timing for unknown codes so response time cannot enumerate valid codes. 403 — caller is not the scoped portal credential (portal-only since #1441).

Create-draft: mint a reserved application_id + HH-[a-f0-9]{8} code + 12-digit passcode + an empty client-side-encrypted draft row (keyed on the reserved id, no FK to applications). The HH-… code is only ~32 bits, so the store-layer insert is wrapped in a bounded collision-retry (10 attempts) on the application_id_codes.code UNIQUE constraint — the retry the MR4 generator deferred to its live-DB caller.

Minimum role: the portal’s citizen-class credential only, since #1441 (azp allowlist + portal:intake scope). Any other principal, service class included, returns 403 portal_only_route.

Response (201): CreateDraftResponse — { "application_id": "uuid", "code": "HH-…", "passcode": "NNNN-NNNN-NNNN", "kdf_salt": "<base64>", "enc_version": 1 }. The raw passcode is returned once, over TLS, so the client can derive the Argon2id draft key; the server persists only the one-way hash + the non-secret kdf_salt. 403 — caller is not the scoped portal credential (portal-only since #1441).

Patch-draft: replace the per-step ciphertext for a reserved-id draft and slide the 30-day expiry (expires_at = now() + 30 days).

Minimum role: the portal’s citizen-class credential only, since #1441 (azp allowlist + portal:intake scope). Any other principal, service class included, returns 403 portal_only_route.

Request:

The server stores ciphertext / nonce blind — it never decodes the plaintext.

204 — draft updated. 404 — no draft with that reserved id. 422 — malformed base64 ciphertext / nonce, or current_step outside 1–4 (rejected at the handler, not as a DB CHECK 500). 403 — caller is not the scoped portal credential (portal-only since #1441).

Get-draft (#727 resume): return the stored ciphertext blob so the passcode-holding WASM client can decrypt the saved step locally and pick up where it left off. Shares the {id} path with patch-draft (GET vs PATCH are distinct operations on the same path item). The server reads the ciphertext blind — only the client decrypts. The portal POST /apply/resume proxy supplies {id} from a freshly verified credential (verify-credential → reserved id), never client input — the IDOR boundary lives in the BFF.

Minimum role: the portal’s citizen-class credential only, since #1441 (azp allowlist + portal:intake scope). Any other principal, service class included, returns 403 portal_only_route.

Response (200): GetDraftResponse —

ciphertext / nonce are empty strings for a draft created but never saved (the client treats that as a blank form at step 1, still bound to the same reserved id). 404 — no draft with that reserved id, or it has expired (expires_at ⇐ now()): a stale-but-unreaped row is never served. 403 — caller is not the scoped portal credential (portal-only since #1441).

Materialise-at-finalize (Plan 3 MR6c). The client submits the plaintext application (FinalizeRequest — the primary applicant, household_members, income, assets, expenses (each serde(default) — omittable), programs_requested, ele_consent, optional notify_email / notify_phone_e164, optional address (#1137 — the apply-wizard address, claimed as the head’s residential canopy-persons fact effective from the filing date, so a portal-filed household resolves a notices recipient without worker intervention; omittable — filing is never conditioned on an address), and confidentiality (#1137 — the wizard’s safety election, standard/confidential/address_confidential/both, persisted to applications.confidentiality; confidential/both disable self-serve recovery per applicant-portal design ref §3.8)); canopy-applications creates persons → household → members → address → income / assets / expenses over the canopy-persons service API (ADR-019 service token), then in one transaction inserts the applications row with the reserved id (status submitted) + per-program rows and deletes the application_drafts row — keeping the credentials, which become the submitted application’s login. The reserved-id draft is SELECT … FOR UPDATE-locked first, so this serialises with the reaper.

The income/asset/expense entries are authored into the canopy-persons version corpus (T1-7 #675) as applicant self-report claims — Author::Applicant (the finalize-resolved household_id, ADR-027 §9 — no portal-session identity), self_attestation source, auto-accepted accepted_unverified (which feeds determinations) — each emitting an attributed {income,asset,expense}.claimed event (per-fact, unbatched; see canopy-persons § Events Published). Every fact’s person_index + amount is validated before any cross-service write, so a malformed fact 422s without orphaning persons rows.

Minimum role: the portal’s citizen-class credential only, since #1441 (azp allowlist + portal:intake scope). Any other principal, service class included, returns 403 portal_only_route.

The persons writes span canopy-persons (a separate service/DB per ADR-001) and are not in the local transaction — the single-transaction guarantee is specifically the applications INSERT + draft DELETE pair (ADR-026 §5). A finalize runs an early non-locking existence check before those writes, so a draft that is already gone 404s without orphaning persons rows.

Two paths behind finalize_saga_enabled (default off until epic &71 MR8; see ADR-038). With the flag on, finalize runs as the recoverable saga: a linearizable draft-row-locking claim on finalize_operations serialises concurrent attempts; every persons write carries the idempotent (operation, generation, step) receipt tag; a resumed attempt skips receipted steps (local finalize_steps cache) and rebuilds its remaining writes from the pinned basis_date and the digest-validated original request (a keyed HMAC digest binds each generation to its request bytes — an edited request cannot resume); the final transaction is network-free (draft lock → applications INSERT → lease-fenced mark_completed → draft DELETE); persons events stay held until the post-commit release, so downstream never sees a partial finalize. With the flag off, the pre-saga flow runs (persons writes untagged, the ADR-026 §5 orphan window retained).

Response (201): FinalizeResponse — { "application_id": "uuid", "household_id": "uuid" }. The application_id equals the reserved draft id. When ele_consent is true, finalize emits application.ele_consent_recorded (consent_source = "applicant_portal"). On the saga path a retry of an already-completed finalize replays the identical 201 (retry-after-lost-response) with no new persons writes.

404 — no draft with that reserved id (reaped / already finalized). 422 — unknown program, an income/asset/expense person_index out of range, an unparseable amount/value, or a malformed address (blank line_1/city, a non-two-letter state, or a ZIP outside 5–10 chars — validated before any cross-service write, #1137). 403 — caller is not the scoped portal credential (portal-only since #1441). 409 — on the saga path, the request differs from the attempt already in flight for this draft (pinned request-digest mismatch); on any path, an Idempotency-Key reused with a different body (the platform idempotency layer wraps every service route). 503 + Retry-After — on the saga path, another attempt holds the operation lease or the reconciler is compensating; on any path, an in-flight Idempotency-Key duplicate. Retry after the indicated seconds.

Draft-reaper admin trigger (Plan 3 MR6d, ADR-026 §6). Deletes every expired draft (expires_at < now(), where expires_at is last_saved_at + 30 days rewritten on every save) and its reserved credentials (application_id_codes + passcode_hashes) on demand, and returns the count. The same sweep runs unprompted on a daily background tick (leader-elected across replicas via run_with_advisory_lock); this endpoint forces it (e.g. after a retention-policy change) and makes the timer-driven job HTTP-testable.

The sweep is one transaction that SELECT … FOR UPDATE SKIP LOCKED`s the expired drafts, then does explicit ordered deletes (`passcode_hashes → application_id_codes → application_drafts) — deliberately not ON DELETE CASCADE, because finalize deletes a draft while keeping its credentials (they become the submitted app’s login), so the cascade direction must not exist. SKIP LOCKED serialises with finalize on the draft row: a draft whose finalize is in flight is skipped this sweep, so the reaper never deletes the login of an application that is about to be submitted.

Lease/compensation-aware (ADR-038, epic &71 MR6). The sweep also excludes any expired draft whose finalize_operations row is non-terminal (in_progress / compensating) — the saga may still commit (its final transaction needs the draft row) or the reconciler is mid-compensation. The draft becomes reapable again once the operation is terminal (aborted — by which point the draft’s own 30-day expiry has long passed — or completed, where finalize already deleted it). Relatedly, draft_exists (the finalize fast-fail) is live-only: an expired-but-unswept draft reads as absent, aligned with get_draft and the claim’s expiry-checking lock.

Minimum role: service-class token only — operator tooling, not an applicant-reachable route.

Response (200): ReapDraftsResponse — { "drafts_reaped": 0 }. 403 — caller is not service-class.

Runs the recovery challenge: App-ID gate (resolve the HH-… code to a submitted application) → confidential/locked short-circuit → DOB second factor (verified cross-service against the submitter’s canopy-persons record). On success, mints a 24-hour pending recovery (idempotent against the active-per-app index — a re-initiation while one is pending is absorbed and does not re-notify the contact) and stages application.applicant.recovery_initiated.

Always returns 200; the outcome is in the body, never the status code, so the endpoint is not a case-enumeration oracle:

recent_letter_id / approx_decision_year are accepted (the §3.7 friction challenges) but not yet server-verified — additive, tracked in #662. 403 — caller is not the scoped portal credential (portal-only since #1441).

The "this wasn’t me" one-tap kill-switch (applicant-portal design ref §3.4/§3.7). Cancels the active pending recovery for that kill-switch token (a 256-bit secret carried in the notification) and locks the case (applications.recovery_locked — a worker must clear it before self-serve recovery is available again), staging application.applicant.recovery_killed.

Response (200): RecoverKillResponse — { "application_id": "uuid" }. 404 — no active recovery for that token (unknown / already terminal; the token is a secret, so this is not a meaningful oracle). 403 — caller is not the scoped portal credential (portal-only since #1441).

The internal read the canopy-notices recovery subscriber calls to compose the side-channel notification. The application.applicant.recovery_initiated event carries only IDs + the reveal timestamp (ADR-004), so the application-time contact + the kill-switch token are read from the recovery_pending row here — off the broadcast bus. Service-caller only; never applicant-reachable.

Response (200): RecoverDetailResponse — { "application_id": "uuid", "kill_switch_token": "…​", "reveal_at": "rfc3339", "notify_email": "…​", "notify_phone_e164": "…​" } (notify_* may be null). No passcode (value or hash) is ever returned. 404 — no recovery with that id. 403 — caller is not service-class.

Designate an authorized representative on a household.

Minimum role: caseworker.

Request:

List active representatives for a household.

Minimum role: caseworker.

Fetch a single representative.

Minimum role: caseworker.

Update relationship, consent flag, or expiration date.

Minimum role: caseworker.

Soft-delete (active = false). The row stays for audit.

Minimum role: caseworker.

Assign a worker to a household.

Request:

Response (201): the new HouseholdAssignment row.

Soft-delete an assignment. Returns 204 on success, 403 if the on-behalf-of actor is not supervisor/admin, 404 if the id is unknown or the row was already unassigned.

List active assignments for a worker.

One keyset page of the worker’s ACTIVE-assignment household ids (#596) — the IDs-only authorization projection (ADR-001 Amendment 1 §B4 data minimization) consumed by canopy-eligibility’s cross-program-alerts scoping. Query params: limit (clamped [1, 200], default 50) and after (keyset cursor, strictly-greater household id). Response {items, next_cursor} per §B2: a full page carries next_cursor = the last item; a short page is the end. Ordered by household_id ascending, riding the active-only partial unique index. Service-caller only.

List active assignments for a household. Hot-path query consumed by canopy-enrollment’s RBAC gate.

Upload a document as multipart/form-data. The file flows through the zero-trust canopy-store::validate_upload pipeline (#435 — size, magic-byte verification, MIME allowlist, SHA-256, filename sanitisation); on success the object is stored under {program}/{application_id}/{sha256} and the metadata row is returned quarantined at scan_status = pending (ADR-042/#1006): scanning is asynchronous — the promotion worker settles pending → clean | infected | skipped | error with full provenance (scan_backend, scan_backend_version, scanned_at, scan_detail), and every serving/review surface gates on the derived scan_viewable (clean, or skipped carrying the audited supervisor override).

Parts: file (required — the bytes, with a filename + Content-Type), person_id (required — the person the document is about), document_type (required — identity / income / residency / citizenship / other), document_kind (optional — photo_id / ssn_card / pay_stub / lease / other), program (optional — storage namespace, defaults to snap), uploaded_by_source (optional — applicant_portal (default) / worker_intake).

Response (201): ApplicationDocument — the post-validation metadata, including the lowercase-hex sha256, the derived review_status (pending / accepted / rejected), the typed scan_status (ADR-042 — the noop token is dead), and scan_viewable (always false at upload). scan_detail (AV signature names / skip reasons) is worker-facing: the portal BFF projects it away before anything reaches an applicant’s browser. The storage path (s3_bucket / s3_key) is intentionally not exposed — fetch the bytes via the content endpoint. 404 — unknown application (checked before any object is written, so a bad id never orphans an object). 422 — empty / oversize file, MIME mismatch or disallowed type, or a missing/invalid required field. 403 — caller is neither a service-class principal nor the scoped portal credential (#1441).

The service-wide request body limit is raised to 11 MiB on canopy-applications (10 MiB per-file ceiling + multipart-framing headroom); validate_upload is the authoritative per-file size gate.

List an application’s documents, newest first. Response (200): [ApplicationDocument]. 403 — caller is neither a service-class principal nor the scoped portal credential (#1441).

Serve the stored bytes back (worker preview) with the original Content-Type and Content-Disposition: inline (the global nosniff header still applies). Since ADR-042 this endpoint is the quarantine’s byte gate: it refuses 409 unless the document is scan-viewable, re-reads the FULL object (bounded by the 10 MiB upload cap) and re-verifies sha256+size against the row before serving — a replaced object is unservable regardless of scan state — and stamps Cache-Control: no-store on every response (success and error), so a browser can never replay bytes past a later quarantine. 404 — no document with that id under this application. 409 — quarantined (pending / infected / un-released skipped / error). 403 — caller is not service-class.

Worker accept. No request body (#1009, pre-1.0 break — the former AcceptDocumentRequest { accepted_by } was spoofable by any trusted service-class caller): the reviewing worker arrives ONLY as the verified ADR-019 X-Canopy-Actor JWT (minted by canopy-web with its web-actor key; this service verifies signature/audience/expiry via its ActorVerifierAdapter and projects the verified sub onto accepted_by). Sets accepted_at / accepted_by and clears any prior rejection (accept + reject are mutually exclusive). Response (200): the updated ApplicationDocument (review_status = accepted). Since ADR-042 the viewability predicate lives INSIDE the UPDATE (no check-then-update race; ck_docs_accepted_viewable backstops in the DB): 409 — quarantined, not acceptable until scan-viewable. 404 — no document with that id under this application. 403 — caller is not service-class, or no verified actor accompanied the request (a review must name a real reviewer — Pub 1075 §9). 422 — the verified actor subject is not a worker UUID. (A PRESENT-but-invalid actor JWT — expired, wrong audience, bad signature — is 401 at the auth middleware before the handler runs; only a wholly ABSENT actor reaches the 403 here.)

Worker reject. Body: RejectDocumentRequest — { "rejection_reason": "…" } (required, non-empty). The rejecting worker comes from the verified X-Canopy-Actor claim exactly like accept (#1009) and lands on the new rejected_by column. Sets rejection_reason / rejected_by and clears any prior acceptance. Response (200): the updated ApplicationDocument (review_status = rejected, rejected_by populated). 409 — quarantined: review is a content judgment, so rejection too requires a scan-viewable document (ADR-042). 404 — no document with that id under this application. 422 — empty rejection_reason, or a non-UUID actor subject. 403 — caller is not service-class, or no verified actor.

Release a quarantined-skipped (unscannable — e.g. password-protected) document: the ADR-042/ADR-041 audited accountable override. Requires a verified X-Canopy-Actor whose realm roles include supervisor or admin — enforced at THIS origin, not just the BFF affordance. Body: ScanOverrideRequest — { "reason": "…" } (8–500 chars after trim). Valid only from skipped with no prior override; the reason lands on the row and its SHA-256 digest rides the application_document.scan_overridden audit event (never the prose — ADR-004). Response (200): the updated ApplicationDocument (scan_viewable = true). 409 — not skipped, or already overridden (a duplicate POST is a clean conflict). 404 — unknown document. 403 — caller not service-class, no verified actor, or the actor lacks a release-authorized role. 422 — reason out of bounds, or a non-UUID actor subject.

Service-only requeue for a fresh scan (the supported recovery for terminal error rows — no direct SQL): atomic reset to pending under a bumped scan generation; provenance, attempts, claim, override, and any standing acceptance clear (the verdict is in doubt; application_document.scan_requeued — plus acceptance_revoked when an acceptance fell — stage in the same transaction). ADR-007 CLI parity: canopy application document-rescan --application-id … --document-id …. Response (200): the updated ApplicationDocument (scan_status = pending). 409 — already pending. 404 — unknown document. 403 — caller is not service-class.