canopy-persons API Reference

Create a person. SSN is encrypted at rest via AES-256-GCM before storage.

Request: CreatePerson

Response (201): Person object. The full SSN is never returned — only ssn_last_four (e.g. "6789") is exposed.

List persons with keyset pagination and infix name search, newest first.

Query parameters: limit (page size), after_created_at + after_id (keyset cursor — the previous page’s last (created_at, id); omit both for the first page), search (infix ILIKE on first/last name, pg_trgm-GIN-indexed; minimum 2 characters — a shorter query returns 400). Results are ordered created_at DESC, id DESC. #1209 (scale audit H4) replaced the former offset with this keyset cursor and added the server-side minimum-length gate.

Get a single person by ID.

Update a person’s demographic data.

Delete a person.

Create a household.

Request: CreateHousehold

Response (201): Household object.

Get a household with all members.

Query: as_of (optional) — the valid-time anchor (T2-1 A2, #683). Absent / empty / now (case-insensitive) is the current read (today); a YYYY-MM-DD value reads the membership in effect on that date from household_member_versions; a malformed value returns 400.

Response (200): HouseholdWithMembers — the member list (each HouseholdMember carrying its relationship + the additive provenance: Option<Provenance>) is the current-accepted membership versions valid on as_of. Since T2-1 A2 (#683) membership is valid-time-versioned (household_member_versions), so a future-effective or already-closed membership is omitted; writes go through /members/claims (below).

Author (claim) a household membership — the authored versioned-write path (ADR-027), mirroring the per-person /claims endpoints. T2-1 A2 (#683). The membership lands as an attributed, valid-time-versioned, non-overlapping row in household_member_versions, including retroactive corrections. Because the URL is household-scoped, the subject person_id rides in the body (not the path).

Request: MemberClaimRequest (person_id + value: {relationship} + the provenance inputs source / author / origin + valid_from / valid_to? / fact_id?). As with the other claims, the server derives claim_status (worker → accepted_verified, applicant → accepted_unverified) and owns recorded_at; fact_id absent = a new membership (server-generated handle, ADR-025), present = a valid-time correction (a supplied fact_id must already belong to the path household_id — an ownership probe, 404 on a wrong pair; and its stored person_id must match the body person_id — a correction may not reassign a membership to a different person, 422 on a mismatch). Membership has no numeric value, so the 422s here are a System author or a body person_id/household_id that violates an FK (23503 → 422). A double-add — an overlapping membership for the same (household_id, person_id) via a new fact_id, or a correction extending one fact to overlap another — trips the per-(household_id, person_id) non-overlap EXCLUDE → 409.

Response (201): ClaimResponse (version_id, fact_id, claim_status). Emits an attributed household.member_claimed event (the full MemberFactValue rides the payload — relationship is not PII, so unlike the street-redacted address events no coarse projection is applied — alongside household_id + the before/after windows).

Close (remove) a household membership as of a date (T2-1 A2 #683 — the membership remove primitive; mirrors the income/address close). Query: as_of (optional, default today) — the close date. Supersedes the current accepted version and re-tiles only the left remnant [valid_from, close_date), so the membership drops from as-of≥close_date reads while history before the close date is preserved. Emits household.member_closed (full value) only when the close superseded ≥1 window. Idempotent 204; a fact_id not owned by the path household_id is 404.

Get a household with every member fully expanded.

Query: as_of (optional) — the valid-time anchor (T1-4 Slice 3, #672). Absent / empty / now (case-insensitive) is the current read (today); a YYYY-MM-DD value reads the facts in effect on that date from the version corpus; a malformed value returns 400. The eligibility orchestrator forwards the determination’s as_of here, so a retroactive determination reads the facts that were in effect then.

Response (200): HouseholdFull — { household, members: [MemberFull] }, each MemberFull carrying the member’s relationship; the household’s membership roster itself is now an as-of valid-time read (the current-accepted household_member_versions valid on as_of — members joined the version corpus in T2-1 A2, #683), and each member’s income / assets / expenses / addresses are the current-accepted versions valid on as_of (carrying provenance — addresses joined the version corpus in T2-1 A1, #683). Returns 404 if the household is unknown.

A household member is included regardless of person.active — membership is authoritative, so a member whose person record was soft-deleted (without the membership being cleaned up) is still returned, preserving household_size for determination. This differs from :batchGet below, which skips soft-deleted persons.

Get a PROJECTED bundle for an arbitrary set of people (person-keyed; used by the CMS-416 reporter to page the Medicaid roll). Capped at 500 IDs per request (422 on overflow). Missing or soft-deleted IDs are omitted.

Since #1223 (ADR-001 Amendment 1 §B4) the request carries a REQUIRED projection field mask: the person core (names, DOB, demographics) always returns; each listed group — person_ssn / income / assets / expenses / addresses — is additionally fetched. Unprojected groups come back empty/null, cost zero queries and zero payload, and — for person_ssn — the sealed SSN is NEVER decrypted and NO Pub-1075 ssn.accessed event is emitted. The empty mask is the CMS-416 shape: one DOB per member (the old full-bundle fetch moved 3–6GB and staged ~2M spurious ssn.accessed events per GA run).

Since #1203 the request also carries an OPTIONAL as_of valid-time anchor (YYYY-MM-DD): the projected facts are read from the version corpus as of that date. Absent/null = today — the interactive-caller semantics, not a compat shim; the reporting run pipeline pins as_of = period end so a resumed extract reads the facts in effect for the report period.

Request: BatchGetPersonsRequest

Response (200): Vec<MemberFull> — each with relationship: null (no household context for a person-keyed query).

Get the COMPACT as-of membership roster for a set of households in one call (#1203, D5 row 1) — the report pipeline’s replacement for the per-household GET /full walk. 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.

Deliberately NOT HouseholdWithMembers/HouseholdFull: no household core, no valid-time windows, no provenance, and no person core — each member is just { person_id, relationship }, so a 500-household response stays bounded under the 2MiB idempotency-replay cache. Because no sealed envelope is opened (no SSN, no DOB), the endpoint stages zero Pub-1075 ssn.accessed events — membership is not a §B4 sealed group.

Absent semantics: a household that is missing or active = false is simply ABSENT from the result — consumers diff the requested id set against the response (the reporting fold maps each absence to a per-universe-row skipped_orphan). An ACTIVE household with no current-accepted membership on as_of is PRESENT with an empty members roster — an honest empty answer, distinct from absence. Membership comes from the valid-time household_member_versions corpus (the same as-of read as GET /full), in two fixed set-based queries (active-household probe + membership corpus read).

Request: BatchGetHouseholdsRequest — as_of is REQUIRED (every bulk caller states its read date; the reporting runs pin the period end).

Response (200): Vec<HouseholdMembershipSlim> — [{ household_id, members: [{ person_id, relationship }] }].

List a person’s facts of that kind as-of today (the current-accepted version valid today per fact, claim_status-filtered to determination-feeding — Proposed/Rejected never appear). Each row carries provenance (author / source / claim_status / origin / recorded_at), and id is the stable fact_id (it survives corrections — the edit/remove handle). For a historical read, use GET /v1/households/{id}/full?as_of=…. (The legacy POST/PUT/DELETE on these paths were removed — writes go through /claims.)

Since T2-6 MR8 (#687, ADR-036) the PII value columns are crypto-shred-sealed at rest (income amount/employer_name, asset value/description, expense amount, address line_1/line_2); the read opens them server-side. A redacted fact (its DEK shredded — see Redaction below) still appears in the read (the version row is append-only) but with its value fields null and redacted: true + redacted_at set — an expungement is auditable, never silently dropped. Structural discriminators (income_type/frequency/address_type/city/state/zip/…) survive redaction. Consumers computing eligibility MUST skip a redacted fact (the orchestrator does so before a determination).

Since T2-1 A1 (#683) addresses are valid-time-versioned (address_versions), exactly like the other facts. This GET lists a person’s addresses as-of today (the current-valid version per fact), each carrying provenance, with id = the stable fact_id. A future-effective or already-closed address is not "current" and is omitted. Writes go through /addresses/claims (below); the flat POST /v1/persons/{id}/addresses + the CreateAddress DTO were removed. The bulk export reads all current windows (not as-of-today) so no held address is lost.

Request: IncomeClaimRequest (value: {income_type, amount, frequency, employer_name?} + the provenance inputs + valid_from / valid_to? / fact_id?).

Request: AssetClaimRequest (value: {asset_type, value, description?} + provenance inputs + window + fact_id?). The verification state is the derived claim_status.

Request: ExpenseClaimRequest (value: {expense_type, amount, frequency} + provenance inputs + window + fact_id?).

Request: AddressClaimRequest (value: {address_type, line_1, line_2?, city, state, zip, county_fips?} + provenance inputs + window + fact_id?). T2-1 A1 (#683). Addresses have no numeric value, so the only 422 here is a System author (never a negative amount). The emitted address.claimed event carries a coarse, street-redacted value (address_type/city/state/zip/county_fips — never line_1/line_2): the precise street is privacy-sensitive (the canopy-mq guard is top-level-keys-only, so the street is kept out of the outbox / audit ledger entirely; the full value persists only in address_versions, per ADR-004 / ADR-027 §8).

Honors the ADR-038 finalize step tag like the income/asset/expense claims (#1137): an X-Canopy-Finalize-*-tagged write is receipted (address:{i} — replay returns the original fact, writing nothing), its address.claimed stages held until the operation’s release, and a cancelled generation compensates the address fact (version superseded, address_version DEK shredded) alongside the rest of the graph.

Close (remove) an income fact as of a date (T1-4 Slice 3 — the remove primitive). Query: as_of (optional, default today) — the close date. Supersedes the current accepted version and re-tiles only the left remnant [valid_from, close_date), so the fact drops from as-of≥close_date determination reads while history before the close date is preserved. Idempotent 204; a fact_id not owned by person_id is 404. (A bounded-valid_to correction would re-tile a right remnant and NOT remove — hence the dedicated close.)

Close (remove) an address fact as of a date (T2-1 A1 #683 — the address remove primitive; mirrors the income close). Query: as_of (optional, default today). Emits address.closed (coarse, street-redacted) only when the close superseded ≥1 window. Idempotent 204; a fact_id not owned by person_id is 404.

Redact one fact (kind ∈ income | asset | expense | address): shreds the fact’s per-fact DEK, so every version of the fact reads redacted. Request: RedactRequest ({ reason }). Response (200): { fact_id, kind, redacted_at }. 404 for an unknown kind or a fact_id not owned by the person; 400 on a blank reason; 403 without data_steward. The sub-resource …/redact form is required (axum/matchit 0.8 rejects the AIP-136 …:redact colon).

Redact a person’s SSN: shreds only the per-person SSN DEK — date_of_birth (a separate DEK) and the person’s facts are unaffected (ADR-036 Decision D). After redaction ssn_last_four reads null. Request: RedactRequest. Response (200): { person_id, redacted_at }. 404 for an unknown person; 400 on a blank reason; 403 without data_steward.

Open the (op, gen) generation gate (state = active) so tagged writes are accepted; idempotent upsert. Response (200): RegisterResponse — an already-cancelled generation reports cancelled (the caller must bump the generation for a fresh attempt, never reuse it).

Un-hold every event the operation staged (hold_operation_id = NULL) once the application has committed, so the drainer publishes them. Idempotent. Response (200): ReleaseResponse (released = rows un-held).

Compensate an aborted operation, in one transaction: (1) mark the generation cancelled (taking the row’s write lock, which serializes with the FOR SHARE a tagged writer holds — a stale in-flight write commits its receipt first or is refused); (2) re-inventory the receipts after the mark; (3) drop every still-held event for (op, gen) (downstream never sees a compensated operation); (4) per receipted entity, under a per-fact / per-person / per-household lock: crypto-shred the inventoried DEK + deactivate an exclusively finalize-owned entity, or quarantine (leave intact, record for a data steward) one a later non-finalize write shares — the per-fact DEK is shared across a fact’s versions, so shredding a shared fact would destroy the correction’s value. Quarantine is terminal and never blocks the operation reaching aborted. Idempotent + resumable. Response (200): CancelResponse (events_dropped, compensated[], quarantined[]).

A PII-free view of the operation’s generations + receipts for the reconciler. Response (200): FinalizeOperationView.

Compensate one pre-saga orphaned finalize graph — a household with a finalize-authored self membership that no application references and no finalize receipt covers (the pre-epic-&71 finalize_draft crash residue the cargo xtask sweep-finalize-orphans tool discovers; see the operator runbook).

Minimum role: data_steward (ADR-036 Decision M — a human steward surface, NOT the applications-only service surface above; admins do not inherit it). A require_user_only route (#1428) — same posture as the redact routes.

In one transaction, under the household advisory lock: verify the household exists (else 404); verify the finalize self-membership provenance (else 409 — ambiguous graphs are steward-manual, never auto-shredded); inventory every finalize-authored entity reachable from the household (memberships → member persons → their finalize income/asset/expense facts); refuse if ANY finalize receipt references the graph (409 — saga-era, owned by the finalize reconciler’s cancel path); then compensate each entity through the same shred-or-quarantine machinery as cancel — crypto-shred the inventoried DEK + deactivate/supersede an exclusively finalize-owned entity, quarantine (leave intact, report) one shared with non-finalize data, including a person holding a current finalize membership in a different household. Idempotent — a replay re-walks the graph and no-ops per already-compensated entity. Response (200): OrphanCompensationResponse (household_id, compensated[], quarantined[] — PII-free).

User-only (admin or quality_control) bulk export with FOIA / portability disclosure modes (#1428: service bearers 403; enforced routes require an exchanged per-target token).

Minimum role: admin or quality_control (a require_user_only route)

Query parameters:

In foia mode each row is a FoiaPerson (year-only birth date, street redacted via FoiaAddress; names retained). In portability mode each row is a PersonWithAddresses (full Person joined to full Address rows for the single named subject).

Response (200): full or FOIA-redacted records (CSV or JSON per format). Returns 400 for an invalid window/mode or a missing person_id when mode=portability, and 403 when the caller lacks the admin role.