Skip to main content

​
Create: Children First

Individuals stand alone; business-family entities reference individuals. So the creation order for anything but a lone individual is:
1

Create the individual entities

Every beneficial owner, control person, or sole proprietor is an individual entity created first, meeting authorized-signer data requirements. Capture each entity_id.
2

Create the business or sole-prop entity

Reference the individuals in beneficial_owners / control_persons (business) or sole_proprietor (sole prop). Who must be listed and the drill-down rule for indirect ownership: Beneficial Ownership Requirements.
3

Validate eligibility as you go

Pass intended_roles to validate role readiness synchronously, or read role_details on the response (Roles). A parent’s eligibility depends on its children passing their checks — failures point at the failing child’s entity_id (Troubleshooting).
Entity Creation Workflow Requests are idempotent via the required Idempotency-Key header, and client_customer_id must be unique — a create with an existing value returns 409 rather than a duplicate entity.

​
Create and Update Validations

An entity records who your customer is, and many downstream consumers with different format constraints read from it. Send customer data as your customer presented it, including non-Latin characters in names and addresses. The validations below reject structurally bad data. In addition to standard required-vs-optional and data-type validations, Lead runs the following at the point of entry.
This list is not exhaustive. Lead adds validations as needed to keep entity data accurate for oversight.
  • Phone numbers follow E.123 format — a + sign, country code, and required spacing. The validation regex:
  • Addresses and customer information must consist solely of valid UTF-8 characters.
  • The business name must be longer than one character.
  • P.O. Box addresses may not be used as physical addresses — neither in line 1 nor line 2.
  • Registered-agent addresses and addresses in prohibited countries may not be used as physical addresses.
  • Address line 1 may not have leading whitespace and must be at least 4 characters. (Line-1 vs. line-2 semantics: The Entity Object.)
  • For US addresses, state must be a valid USPS state code.
  • SSNs may not start with the number 9 — ITINs mistakenly reported as SSNs are the most common trigger of this failure.
  • Postal codes for US addresses must be 5 or 9 digits.
  • OFAC and KYC dates must be dated prior to the time of the request.
Violations return a 422 with the offending field named in invalid_parameters (Troubleshooting).

​
Update

PATCH /v0/entities/{id} updates an existing entity. Certain updates re-trigger KYC, requiring an updated kyc_details.result and kyc_details.screened_at alongside the change (Update an Entity). Updates are also how you cure role-eligibility failures: fix the field named in failed_checks, and Lead recomputes role_details — including for any parent entities whose eligibility depends on this one. Entities cannot be deleted; an entity stays attached to its accounts for the life of the relationship.