Customers and KYC

A customer is a person or a business the bank knows. Nothing opens in a customer's name until a KYC check has verified them.

Creating a customer

POST /customers takes one body for both kinds, and type decides which rules apply. The Idempotency-Key header is required.

typestringRequired

person or business.

legal_namestringRequired

At most 200 characters.

emailstringRequired

An email address.

tax_idstringRequired

Nine digits, dashes allowed: an SSN or ITIN for a person, an EIN for a business. It is sealed on the record and never returned. The customer shows tax_id_last4.

addressobjectRequired

line1, city, state, postal_code and a two-letter country, with line2 optional. A US address needs a two-letter state and a ZIP code.

date_of_birthstringRequired for a person

YYYY-MM-DD.

formation_datestringOptional

YYYY-MM-DD, for a business.

phonestringOptional

E.164, for example +15125550100.

A new customer is active, with kyc_status pending, risk_rating unrated and backup_withholding true (see Statements and tax documents).

KYC checks

POST /kyc-checks with a customer_id runs the verification. The compliance service screens the legal name against the sanctions lists, sends the applicant to the identity-verification provider, stores the outcome as a KYC check and records the decision on the customer.

`kyc_status`	Meaning
`pending`	No check has run.
`verified`	The provider verified the customer and the screening was clear.
`review`	The provider asked for manual review, or the screening found a potential match.
`rejected`	The provider rejected the customer, or the screening found a hit.

The check holds the decision, the risk_rating (low, medium or high), the provider with its provider_ref, and the reasons. evidence is present only when an outside vendor made the evaluation, and never holds a document image or a tax id.

Decisions reach the customer through POST /customers/{id}/kyc-decisions. Only the compliance service's result or a staff member may set verified, and any other caller is answered forbidden. Each decision is published as customers.kyc.decided. A change of legal name or address sends a verified customer back to review.

Testing KYC

The provider is a simulator in every environment today. It verifies an applicant with a low rating unless the legal name contains a marker:

REJECT gives rejected with a high rating.
REVIEW gives review with a medium rating.
HIGHRISK gives verified with a high rating, which the opening gate below still refuses.

Business owners and groups

A business's beneficial owners and its control person are customers of type person. POST /customers/{id}/business-parties links them: up to twenty parties, each with a customer_id, an ownership_bps and a control_person flag, plus an evidence_ref, a reason and the expected_version last read. Exactly one party is the control person, and ownership cannot exceed 10,000 basis points. The route takes a service credential with customers:write.

Recording a version returns the business to review. The next KYC check verifies every party too, and a party that is rejected or in review keeps the business from being verified. Outside the local environment a business with no parties on record ends in review, not verified.

A customer group puts a parent business and its subsidiaries or affiliates under one relationship: a name, a parent_customer_id, optional members with a role, and a transfer_policy of any_member (the default) or parent_only, which decides who may start an inter-entity transfer. Only businesses join (customers.not_a_business), and a customer belongs to one group (customers.already_in_group). GET /account-groups/{id} returns each member's open accounts with their balances, and the group total.

The opening gate

Before an account opens, the accounts service asks GET /customers/{id}/eligibility about every owner. A customer is eligible when they are active, verified, of the customer type the product is for, not rated high, and have no confirmed death report. Otherwise POST /accounts answers 422 with the code accounts.customer_not_eligible, and detail lists the reasons.