plan-kyc-singleton-implementation

Author: akanter

docs/plans/2026-07-22-kyc-singleton-implementation.md

@@ -0,0 +1,34 @@
+# KYC singleton flow — implementation plan (Phase 1, grid-api slice)
+
+## Context
+
+Design proposal in [grid-api#700](https://github.com/lightsparkdev/grid-api/pull/700) — approved, currently on R12. This PR is the **Phase 1 grid-api slice**: OpenAPI schema additions and Mintlify sandbox docs. Backend sparkcore work ships as a separate PR in `webdev/sparkcore`. OFAC / LexisNexis handling is treated as separately-scoped work per Aaron.
+
+The full phasing lives in #700's "Implementation phasing" section; this plan documents only what changes in this PR.
+
+## Phase 1 — grid-api items
+
+Roughly one commit per item; ship as a single PR since they all touch the same OpenAPI surface.
+
+- **§1 `taxIdentification[]`** on `IndividualCustomerFields.yaml` (optional array of `{idType, identifier, countryOfIssuance}`; reuses existing `IdentificationType` enum).
+- **§1a Optional EDD extras** on `IndividualCustomerFields.yaml` — `sourceOfFundsCategories`, `sourceOfWealthCategories`, `purposeOfAccount`, `expectedMonthlyTransactionCount`, `expectedMonthlyTransactionVolume`, `annualIncomeRange`, `netWorthRange`, `pepStatus`. Reuse existing shared schemas (`SourceOfFundsCategory`, `PurposeOfAccount`, `ExpectedMonthlyTransactionCount/Volume` — all already used by `BusinessInfo`). New enum schemas for `SourceOfWealthCategory`, `AnnualIncomeRange`, `NetWorthRange`, `PepStatus`.
+- **§2 `VerificationError` enhancement** — add optional `code` (stable machine code) and `constraint` (regex / enum / length / format) on `VerificationError.yaml`.
+- **§5 `submitForVerification` flag** on `POST /customers` and `PATCH /customers/{customerId}` — new optional boolean on the request body; when `true`, response wraps `{ customer, verification }`. New `CustomerCreateResponse.yaml` / `CustomerUpdateResponse.yaml` response schemas that carry the optional embedded `Verification`.
+- **§3 `GET /verification/requirements`** endpoint spec + `VerificationRequirements.yaml` response schema (with helper `FieldRequirement.yaml`, `DocumentRequirement.yaml`, `AddressFormat.yaml` inner schemas).
+- **Mintlify docs** — rename `mintlify/snippets/sandbox-kyb-verification.mdx` → `sandbox-verification.mdx`; add "Individual customer verification" subsection with the `fullName` last-3-chars → `001` PENDING / `002` REJECTED / else APPROVED table; update imports in `mintlify/api-reference/sandbox-testing.mdx` and any per-product `sandbox-testing.mdx` pages.
+- **`openapi/openapi.yaml`** — register the new `/verification/requirements` path and new schema components.
+- **Regenerate `openapi.yaml`** at the repo root via `make build` (the bundled root spec is generated from the split schema files per grid-api CLAUDE.md).
+
+## Verification
+
+- [ ] `make build` succeeds (OpenAPI bundle regenerates without errors).
+- [ ] `make lint` passes (Redocly OpenAPI lint + Mintlify openapi-check).
+- [ ] Manual spot check of the bundled `openapi.yaml` — new schemas resolve, no dangling refs.
+- [ ] Mintlify preview renders the updated sandbox snippet (via `make mint` locally when reviewing).
+
+## Risks
+
+1. **grid-api is a public repo** — once shipped, all field names / enum values / endpoint shape are external contracts; can't be removed without a breaking change. Everything here is additive and considered final on merge.
+2. **New enum schemas** (`SourceOfWealthCategory`, `AnnualIncomeRange`, `NetWorthRange`, `PepStatus`) — the exact enum values are open to bikeshedding. Current proposal mirrors what's in the design doc §1a; can iterate on values if pilot-customer feedback pushes different buckets.
+3. **`VerificationError.code` values** — schemas allow any string; the canonical set of stable codes gets defined incrementally in Phase 2 backend work. Phase 1 just ships the field.
+4. **`GET /verification/requirements` returning the "real requirements matrix in sandbox"** — this contract is documented in #700 §7 but the backing cache is a Phase 1 backend item (sparkcore PR). Until the backend ships, calling this endpoint in sandbox returns a hard-coded seed matrix; the wire shape is the same.