type: individual, business, and sole_prop. All three share the attestation and metadata fields; they differ in their details object and in how they link to other entities. Create with POST /v0/entities and a required Idempotency-Key header (up to 255 characters).
Common Fields (All Three Shapes)
individual_details (Required for individual)
Required within it: first_name, last_name, and identification_details. First name must be at least 1 alphanumeric character. Last name must be at least 2. The identification_details object must always be present, but only its type is required — whether it must also carry a tax identification or identification documents depends on the roles the individual will hold (Identification). Every other field is optional to create the entity and becomes required only for the roles that need it (Roles).
business_details (Required for business and sole_prop)
Required within it: name (≥2 characters), identification_details, and address_details.
Linkage Objects Resolving Ownership to People
Business-family entities link to individual entities rather than embedding their data — create the individuals first (Workflow), then reference them:
Each referenced individual must meet authorized-signer data requirements — a child entity failing its checks makes the parent’s role
inactive, with criteria_details pointing at the child’s entity_id (Troubleshooting).
Identification for US and Non-US Entities
Theidentification_details object is required on every entity and is discriminated by type — whether the entity has a US tax identification. Only type is required to create the entity; what must accompany it depends on the roles the entity will hold:
Field rules for each shape:
us_entity—tax_identificationwithtype(ssn/itin/ein) and a 9-digitvalue. Rules: SSNs must not start with 9 (ITINs mistakenly reported as SSNs are the most common failure); EINs begin 00–99; ITINs begin with 9. Individuals: SSN or ITIN. Businesses: EIN — except single-member LLCs with no EIN, where SSN or ITIN may be used. Sole props: any of the three.typeis only a discriminator —us_entitywith notax_identificationis accepted. For a US person whose tax identification you do not collect yet, sendus_entityso the record does not have to switch type when you add it later.non_us_entity— at least one government-verifiedidentification_documents[]entry for any role other thanauthorized_user(see the table above). Per entry:type,identification_number,issuing_countryrequired (plusissuing_statefor US-issued,expiration_date,descriptionwhen type isother). Individual document types:drivers_license,state_or_provincial_id,passport,permanent_residency_id,military_id,national_id,matriculate_id,other. Business types:tax_certificate,tax_returns,partnership_agreement,certificate_of_good_standing,formation_document,proof_of_place_on_stock_exchange,other.
intended_roles) and role_details reports CheckGovernmentID against the role (Troubleshooting). Add the identification later with a PATCH. If you have previously submitted kyc_details for the entity, that update must also carry kyc_details with a later screened_at (Update an Entity).
A
us_entity with no tax identification on file returns "tax_identification": { "type": "", "value": "" }. Do not echo that object back on a PATCH; omit tax_identification instead.Example: Authorized User Without a Tax Identification
An individual who will only be anauthorized_user (a teen on a family account, an employee cardholder) needs first name, last name, a contact method, and identification_details.type:
authorized_user as active. The account_holder and authorized_signer entries are inactive, listing the checks the entity has not met, such as CheckDateOfBirth, CheckGovernmentID, CheckKYCStatus, and CheckPhysicalAddress.
To add the individual’s own tax identification later, PATCH the entity. type and the Idempotency-Key header are required on every update. If you have previously submitted kyc_details for the entity, include kyc_details with a later screened_at.
Address Rules
line_1 is the full base address — street number and street name together (or the local equivalent). Address rules protect the structure of the address, not its character set. However you collect address components from your users, combine them into line_1 before sending: do not split the primary street address across lines, do not put only the number in line 1, and never pad line 1 to satisfy validation. line_2 is only for sub-premise information (apartment, unit, suite, floor, building, care-of) — blank otherwise. city and country (ISO 3166-1 alpha-2) are required; US addresses also require a valid USPS state code and a 5-digit postal_code, or ZIP+4 written as 12345-6789 or 12345 6789. Physical addresses must not be P.O. boxes, registered-agent addresses, or in prohibited countries.