canopy-tanf API Reference

Run a TANF eligibility determination. Called by canopy-eligibility orchestrator.

Minimum role: service-or-exchanged (#1425): the orchestrator’s service token, or an exchanged user-context token (aud=canopy-tanf exactly, allowlisted azp, caseworker-or-above role). FTI access attribution (accessed_by) resolves via EffectiveUser — the exchanged bearer’s own sub, or the calling service itself (#1443 retired the verified-actor shape).

Request: ApplicationContext — application context, household composition (AU), per-member income/assets/expenses, SSA data when in scope.

The handler:

Response (200): SignableDetermination — the universal signed-determination envelope (ADR-002) with status, benefit amount, basis, sanction state, time-limit posture, JWS signature, and the snapshot_hash binding the input snapshot (ADR-028). The orchestrator receives only outcome + hash, never the snapshot cleartext (which stays inside canopy-tanf’s Pub 1075 boundary).

Status values emitted: approved, denied, sanctioned (#416 — emitted when the applicant has an active non-expired PAMMS 1351 sanction). denial_reason_code extends with sanction and personal_responsibility per PAMMS 1351 + 1345-1370 respectively.

Response (503, dormant until #1279): when the chain-v2 FTI append arm is enabled (CANOPY_TANF__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 determination aborts fail-closed (a Pub 1075 determination cannot proceed 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 ACF-199 federal universe is gone). The default page rides idx_tanf_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 ACF-199 monthly-caseload 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): TanfDeterminationPage — items (array of TanfDeterminationRead, each the TanfDetermination 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): TanfDeterminationRead — the TanfDetermination 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.

Human-readable explanation of the determination — rule trace, threshold values referenced, and basis. Useful for caseworker review and hearing documentation.

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. TANF 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 (#1425): 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.

Re-evaluate work-requirement status for an AU member.

Minimum role: caseworker.

Request:

Return current work-requirement assignment + status (engaged / partially engaged / unengaged / exempt) and hours required. Get-or-create: a person with no row on file gets a fresh defaults row INSERTed and returned — the interactive/determine surface’s contract, kept deliberately (see the batch sibling below for the read-only alternative).

Minimum role: caseworker.

Get the work-requirement status projection for a set of persons in one round-trip (#1203, D5 row 4) — one person_id = ANY($1) set query replacing the ACF-199 extract’s per-adult GET. 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, even though the interactive per-person GET above stays caseworker-reachable.

READ-ONLY — the hazard this endpoint ends: the single GET above is get-or-create, so the federal ACF-199 read extract was INSERTing tanf_work_requirements rows (a racy SELECT-then-INSERT per adult). The batch NEVER creates a row — pinned by row-count-unchanged tests — while the single GET keeps its get-or-create contract for determine.rs (conversion is a filed follow-up behind a caller audit).

GET-OR-DEFAULT, exact-set: every requested UNIQUE id gets exactly one entry. on_file: false means no row exists; the entry then carries synthesized column defaults (required: true, exempt: false, status: "pending") — except sanction_level, which ships null rather than the column’s DEFAULT 0, because a no-row entry must not fabricate a sanction datum. on_file is the discriminator the extract maps on.

Multi-row history: tanf_work_requirements has no unique(person_id) — multiple rows per person are expected history. The batch projects the NEWEST row by (created_at, id) (deterministic tie-break; the single GET’s read leg orders by created_at alone and leaves equal-timestamp ties to the planner).

Request: BatchGetWorkRequirementsRequest

Response (200): Vec<WorkRequirementStatusEntry> — [{ person_id, on_file, required, exempt, status, sanction_level }].

Log a single work-activity record (countable hours).

Minimum role: caseworker.

Request:

Used to drive ACF-199 WPR (work participation rate) — see canopy-reporting.

List activity records for a person. Filterable by date range.

Minimum role: caseworker.

Aggregated hours for the target month (required ?month=YYYY-MM), broken down by activity type and classified core / non-core per 45 CFR 261.31. ACF-199 WPR source of truth. Pass ?detail=row to attach a per-work_activity_id drill-down under row_breakdown (#406).

Hours beyond a 45 CFR 261.31 countability cap (#1170) are excluded from core_hours: job search past cap_weeks_per_year ISO weeks in the federal fiscal year (Oct 1 – Sep 30) and vocational ed past cap_months_lifetime distinct calendar months, both read from the vocabulary. Usage is derived from the logged rows at summary time (no mutable counter); total_hours keeps the full prorated amount, each breakdown row itemizes its reclassified portion as cap_excess_hours, and cap_usage reports per-type usage against the cap.

Minimum role: caseworker.

Response (200): WorkActivitiesSummary (total_hours, core_hours, non_core_hours, activity_breakdown with per-type cap_excess_hours, optional row_breakdown, cap_usage). 400 on a malformed month.

AIP-231 batch variant of the summary (#1252, ADR-001 Amendment 1 §B4): per-person monthly summaries for a bounded id set in ONE round-trip, backed server-side by ONE person_id = ANY($1) query — the set-based bulk read #320’s closing comment deferred, eliminating the ACF-199 extract’s per-adult GET N+1. Body: BatchActivitiesSummaryRequest (person_ids ≤ 500, month YYYY-MM). One WorkActivitiesSummary per id in first-occurrence request order, duplicates collapsed, zero-hours when a person has no overlapping activities (the single GET’s get-or-zero semantics); no detail=row drill-down (interactive single-person surface only). The #1170 cap reclassification applies per person exactly as on the single GET.

Minimum role: service caller (§B4 bulk reads are service-tier; the interactive per-person GET stays caseworker-reachable — the #1249 least-privilege posture).

Response (200): Vec<WorkActivitiesSummary>. 400 malformed month; 422 over the 500-id cap.

Federal 60-month time-limit posture (months used, remaining, hardship-extension state). Surfaces denial state once months_used >= 60 and no hardship applies. Get-or-create: a person with no row on file gets a fresh row INSERTed (with federal_limit_months snapshotted from the parameter table, #441) and returned — kept deliberately for the interactive/determine surface (see the batch sibling below for the read-only alternative).

Minimum role: caseworker.

Get federal time-limit usage for a set of persons in one round-trip (#1203, D5 row 5) — one person_id = ANY($1) set query replacing the ACF-199 extract’s per-adult GET. 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, even though the interactive per-person GET above stays caseworker-reachable.

READ-ONLY: the single GET above is get-or-create — the same read-that-writes hazard as the work-requirements GET, and its INSERT additionally snapshots federal_limit_months from the parameter table. The batch NEVER creates a row (pinned by row-count-unchanged tests) and ships months_used ONLY — all the extract reads — so a synthesized entry needs no parameter-table value at all: carrying no federal_limit_months avoids fabricating a regulatory snapshot for a person who has no row.

GET-OR-DEFAULT, exact-set: every requested UNIQUE id gets exactly one entry. on_file: false ⇒ months_used: 0 (the column default a created row would carry) — distinguishable from a real stored zero via on_file, never a fabricated tracking claim. Under multi-row history the NEWEST row by (created_at, id) is projected (the single GET’s read leg has no ORDER BY at all — the batch is the deterministic surface).

Request: BatchGetTimeLimitsRequest

Response (200): Vec<TimeLimitStatusEntry> — [{ person_id, on_file, months_used }].

Aggregated active-sanction counts across the jurisdiction, grouped by sanction level + status. Feeds the supervisor dashboard (Stage 5 MR2 #496, FU-9).

Minimum role: supervisor.

Response (200): SanctionsRollup — total_sanctioned, level_1_count, level_2_count, level_3_count, expiring_soon_count.

Record a personal responsibility agreement on an application (school attendance, immunizations, ICW cooperation, etc.).

Minimum role: caseworker.

List the responsibility records on an application.

Minimum role: caseworker.

Update a responsibility’s compliance status (pending / compliant / non_compliant / good_cause / exempt). Non-compliant + gating responsibilities drive denial / sanction in determine.

Minimum role: caseworker.

Record a grandparent-as-caregiver payment.

Minimum role: caseworker.

Request:

payment_type ∈ msp ($100/month Monthly Subsidy Payment) / crisp (one-time Crisis Intervention Services Payment, 4×family-maximum). au_size is required for CRISP.

Response (201): the persisted GrgPayment row.

List GRG payments for a person.

Minimum role: caseworker.

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 (#1425): 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 (rejected with HTTP 400 otherwise).

Response 201: the persisted OverpaymentClaim row (status begins at open).

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. Rejected with HTTP 409 if the claim is closed or written_off.

Append a recoupment ledger entry. Same TX semantics as canopy-snap — first non-zero recoupment flips status to in_repayment; reaching outstanding ≤ 0 flips to closed.

Full ledger view + derived total_recouped_cents + outstanding_cents.

Resolve a pending discrepancy. Sets resolution_status + resolution_notes + resolved_by (via EffectiveUser — the exchanged bearer’s sub, or the preserved 'system' sentinel for a bare service call; #1443 retired the verified-actor shape) + resolved_at = now(). Gated on resolution_status = 'pending' so a second resolve attempt returns 404.

Minimum role: service-or-exchanged (#1425): a service-class caller, or an exchanged user-context token (aud=canopy-tanf exactly, allowlisted azp, caseworker-or-above role) — canopy-web’s #392 BFF action sends the exchanged form when its exchanger is configured.

Request:

Response (200): the updated TanfDiscrepancy row.