Customer
A person or a business the bank knows: identity, KYC status and risk rating. A customer must be KYC-verified before an account opens in their name.
OBJECTThe Customer objectA person or a business the bank knows: identity, KYC status and risk rating. A customer must be KYC-verified before an account opens in their name.POSTCreate a customer
/customers · Create a customer; the tax id is sealed to the record and indexed by a keyed blind indexGETList all customers/customers · Find customers by email or tax id (staff); returns id, name and status onlyGETGet a customer by ID/customers/{id} · Read a customerPUTChange a customer's name, email, phone or address with evidence; a name or address change reopens verification/customers/{id}POSTCapture confidential candidate IDs for an independently reviewed exact 314(a) request across current and historical names, addresses, phones, dates of birth, keyed tax indexes and corrected-tax hashes/customers/information-requests/search · Confidential bounded 314(a) request custodyPOSTSnapshot the payee identity an information return is filed with (the accounts service, or finance staff holding customers:tax:read with a step-up within five minutes): the legal name, address and TIN are copied from the customer record, the TIN sealed to the snapshot; the same filing again returns the snapshot as filed/customers/{id}/as-filed-identitiesGETList a customer's as-filed identity snapshots (last four only)/customers/{id}/as-filed-identitiesPOSTTurn backup withholding on or off by hand (an IRS B-notice, a corrected TIN): customer servicing staff with a step-up within five minutes, or a service with customers:write; every change is evidenced with its actor/customers/{id}/backup-withholdingPOSTRecord a version of a business's natural-person owners and control person; customers:write service credential, idempotency key and expected_version required; reopens KYC review/customers/{id}/business-partiesGETRead the current evidenced ownership and control-person records/customers/{id}/business-partiesPOSTClose a customer (a service with customers:write; staff propose a closure for independent approval instead)/customers/{id}/closePOSTPropose closing a customer (customer servicing staff, step-up within five minutes, idempotency key); a different staff member holding operations:approve decides it/customers/{id}/closuresGETList a customer's closure proposals and their decisions/customers/{id}/closuresPOSTRecord a CRS tax-residency self-certification (customer servicing staff, idempotency key); each residency TIN is sealed to the customer record and never stored in the clear; disabled unless CRS_ENABLED (not a U.S. obligation)/customers/{id}/crs-self-certGETRead a CRS tax-residency self-certification, residency TIN last fours only; disabled unless CRS_ENABLED because the United States is not a CRS participating jurisdiction/customers/{id}/crs-self-certPOSTRecord an unverified death report/customers/{id}/death-reports · Staff evidence onlyGETList death reports for staff review/customers/{id}/death-reports · Staff evidence onlyGETMay this customer open a product of a type/customers/{id}/eligibilityPOSTRecord a version of a passive NFFE's substantial U.S. owners (W-8BEN-E chapter 4 status 24); customer servicing staff, step-up within five minutes, idempotency key/customers/{id}/fatca-ownersGETRead substantial U.S. owners of a passive NFFE; last fours only unless the caller holds customers:fatca:read or customers:tax:read/customers/{id}/fatca-ownersGETThe group a customer belongs to/customers/{id}/groupPOSTRecord a KYC decision; only the compliance service's result or staff may set verified/customers/{id}/kyc-decisionsGETOwn privacy notice history, current policy, sharing election and notice obligations/customers/{id}/privacy · Own verified customer identity or privacy staff authority requiredPOSTRecord or revoke an own nonaffiliate-sharing opt-out, independently of marketing preferences and E-SIGN/customers/{id}/privacy-elections · Own customer identity or fresh privacy staff authority for an evidenced assisted request required; services cannot change electionsPOSTRecord actual delivery of the exact approved privacy notice and electronic agreement evidence where used/customers/{id}/privacy-notices · Privacy delivery service or fresh privacy staff authority requiredPOSTRecord an evidenced active/former consumer relationship; a KYC master record alone is not a relationship/customers/{id}/privacy-relationships · Privacy writer service may assert only its own source_service and product_refPOSTImmediately preserve a customer's records or propose independent hold release or record disposition/customers/{id}/record-controls · Fresh customers:records:write staff authority requiredGETList preserved record-control and independent-decision evidence/customers/{id}/record-controls · Fresh dedicated customers:records:read staff authority and nonempty specific purpose requiredPOSTCapture actual encrypted customer evidence with original source custody and reviewed retention policy/customers/{id}/records · Fresh records writer staff or customers:records:ingest service requiredGETList retained customer record custody and preservation holds with an audited purpose/customers/{id}/records · Fresh dedicated customers:records:read staff authority and nonempty specific purpose requiredPOSTExport only policy-approved customer fields to a named recipient for a permitted purpose; enforce current notices and opt-out atomically/customers/{id}/sharing-exports · A verified service with customers:privacy:share must match the current approved service/recipient/purpose/field grant and supply an actual-use evidence reference/hashPOSTRecord the W-9 or W-8 on file (customer servicing staff, or a service with customers:write); a certified W-9 lifts backup withholding and records its TIN when none is sealed. A W-8's foreign TIN is sealed to the record; a W-8BEN-E carries the entity's chapter 3 and chapter 4 status codes/customers/{id}/tax-certificationsPOSTCapture immutable prepared-document identity with encrypted TIN; this does not assert filing or furnishing/customers/{id}/tax-document-identities · Prepared-document capture does not assert furnishing or filingPOSTPropose replacing the TIN on file (customer servicing staff, step-up within five minutes, idempotency key); the TIN is sealed on receipt and returned as its last four only/customers/{id}/tax-id-correctionsGETList a customer's TIN correction proposals and their decisions (last fours only)/customers/{id}/tax-id-correctionsGETRead the full tax id, and the W-8's foreign TIN and a W-8BEN-E's chapter 3 and chapter 4 status codes: staff with customers:tax:read, a step-up within five minutes and a purpose; the accounts service for information returns; the compliance service with customers:tax:read for KYC. Every read is recorded before the values are returned, with the staff member a service names in on_behalf_of/customers/{id}/tax-identificationPOSTRecord an IRS CP2100 or CP2100A listing against a customer (the accounts service forwarding its record, a service with customers:write, or customer servicing staff with a step-up within five minutes; idempotency key). Backup withholding turns on by withholding_due unless the customer cures the mismatch first: a certified W-9 cures a first B notice, a second needs the TIN validated by Form SSA-7028 or IRS Letter 147C/customers/{id}/tin-noticesGETList a customer's IRS TIN notices: pending, withholding or cured, with the cure/customers/{id}/tin-noticesGETOpen the sealed residency TINs of the current CRS self-certification: staff with customers:crs:read or customers:tax:read and a step-up within five minutes, or the compliance service with customers:crs:read, naming a purpose. Every read is recorded before the values are returned; disabled unless CRS_ENABLED/customers/{id}/crs-self-cert/tax-identificationGETRead a death report and its decision/customers/{id}/death-reports/{report} · Staff evidence onlyGETRetrieve integrity-checked retained evidence for an audited legal or retention purpose/customers/{id}/records/{record} · Fresh dedicated customers:records:read staff authority and nonempty specific purpose requiredGETRead retained prepared-document identity metadata under the restricted tax-reporting purpose/customers/{id}/tax-document-identities/{identity}GETRead a snapshot's as-filed TIN, name and address for a correction: the accounts service for information returns, or staff with customers:tax:read, a step-up within five minutes and a purpose. Every read is recorded, naming the snapshot and the staff member a service names in on_behalf_of, before the value is returned/customers/{id}/as-filed-identities/{identity}/tax-identificationPOSTApprove or reject a closure proposal (customer servicing staff holding operations:approve, not the proposer); an approval closes the customer with evidence/customers/{id}/closures/{closure}/decisionsPOSTPropose correcting a confirmed death report/customers/{id}/death-reports/{report}/corrections · Staff evidence onlyGETRead correction proposals and decisions/customers/{id}/death-reports/{report}/corrections · Staff evidence onlyPOSTIndependently confirm or reject a death report/customers/{id}/death-reports/{report}/decisions · Staff evidence onlyPOSTIndependently decide a hold release or disposition, rechecking current retention and holds atomically/customers/{id}/record-controls/{action}/decisions · Fresh customers:records:approve staff authority, no API key and actor different from maker requiredGETOpen the exact encrypted prepared-document identity, recording the reporting actor before releasing the TIN/customers/{id}/tax-document-identities/{identity}/tax-identification · Same restricted reporting authorityPOSTApprove or reject a TIN correction (customer servicing staff holding operations:approve, not the proposer); an approval swaps the sealed TIN while the one the proposal saw is on file, with an encryption_audit row and evidence, and sends a verified customer back to KYC review/customers/{id}/tax-id-corrections/{correction}/decisionsPOSTIndependently approve or reject a death correction/customers/{id}/death-reports/{report}/corrections/{correction}/decisions · Staff evidence only