Creating users — KYC/KYB required fields

A “user” is one of your end clients — the person or company that owns a virtual account. Creating one with POST /v1/users kicks off identity verification (KYC for individuals, KYB for businesses). The field set you must send depends on two values in the payload: type (individual or business) and address_country (ISO alpha-3, e.g. USA, MEX). Together they put every user into one of four categories.

Two things matter and they are not the same. A bare payload (just the required-to-create fields) returns 201 — but the user will not be product-eligible, and sandbox verification can auto-reject within seconds if KYC data is missing. The authoritative, per-user list of what is still outstanding is the missing_fields map on GET /v1/users/{id} (product_code → [field tokens]) and on the user.created webhook. Treat that map as the source of truth; the tables below tell you what to send up front so you never hit it. See Known limitations and For AI agents.

The four user categories

type and address_country select the required field set:

`type`	`address_country`	Category
`individual`	`USA`	USA individual (KYC)
`individual`	anything else	International individual (KYC)
`business`	`USA`	USA business (KYB)
`business`	anything else	International business (KYB)

International categories drop the US-only fields (ssn, ein, address_state) and add a few of their own (immigration_status, international_entity_type, additional_info). The per-category fields are below.

Country codes are ISO-3 on users (USA, MEX) — not ISO-2. Recipients use ISO-2; do not mix them up. address_country drives category selection, so an ISO-2 value here misroutes the whole payload.

Minimum to create

POST /v1/users only enforces a handful of fields. Everything else is enforced later, by verification and by per-product eligibility.

Category	Required by the endpoint
Individual	`type`, `first_name`, `last_name`, `email`
Business	`type`, `business_legal_name`, `email`

Always send source_of_funds. Sandbox runs verification automatically on create and most commonly auto-REJECTs when source_of_funds is missing — the reason is delivered only in the user.verification.failed webhook (data.reasons[]), never on GET /v1/users/{id}. A rejected user is terminal. See Known limitations.

Required fields by category

To get a user verified and product-eligible, send the full set for its category. Fill scalar gaps later with PUT /v1/users/{id} and re-submit uploads for document gaps; the product flips eligible: true once missing_fields is empty.

Shared identity fields

Sent by every user, individual or business:

Field	Accepted values
`email` · `phone`	Email string · phone string
`address_street` · `address_city` · `address_zip_code` · `address_country`	Free text; `address_country` = ISO alpha-3
`account_purpose`	One of the documented enum values (the set differs for individuals vs businesses — see below)
`source_of_funds`	Enum — differs for individuals vs businesses (see below)
`expected_monthly_volume` · `expected_transaction_count`	Bucketed enums — differ for individuals vs businesses (see below)
`pep_status`	Boolean

USA individual (type: individual, address_country: USA)

Identity

Field	Notes
`first_name` · `last_name`	Free text
`birth_date`	ISO 8601, e.g. `1990-01-15`
`nationality`	ISO alpha-3
`address_state`	Free text (US state)
`document_type` · `document_number` · `document_country`	e.g. `passport`, `drivers_license`, `national_id`; `document_country` = ISO alpha-3
`ssn`	Sent inside `identifying_information`: `[{ "type": "ssn", "number": "…" }]` — required unless `immigration_status` is a non-US citizen status
`identifying_information: front`	Document photo
`identifying_information: back`	Document photo — required unless `document_type` is `passport`

Questionnaire

Field	Accepted values
`employment_status`	`employed` · `self_employed` · `unemployed` · `retired` · `student`
`occupation`	Free text — required when `employment_status` = `employed`
`current_employer`	Free text — required when `employment_status` = `employed`
`income_source`	Free text — required unless `employment_status` = `employed`
`account_purpose`	`receive_payments` · `manage_professional_income` · `make_payments` · `manage_personal_funds` · `investment_trading` · `charitable_donations` · `investment_purposes` · `operating_a_company` · `payments_to_friends_or_family_abroad` · `personal_or_living_expenses` · `purchase_goods_and_services` · `protect_wealth` · `receive_salary` · `receive_payment_for_freelancing`
`source_of_funds`	`salary` · `self_employment_income` · `investment_proceeds` · `savings_inheritance_gift` · `gifts` · `inheritance` · `investments_loans` · `pension_retirement` · `sale_of_assets_real_estate` · `savings` · `someone_elses_funds`
`expected_monthly_volume`	`less_than_10000` · `10000_to_49999` · `50000_to_199999` · `200000_to_999999` · `1000000_or_more`
`expected_transaction_count`	`1_to_10` · `11_to_50` · `51_to_200` · `more_than_200`

International individual (type: individual, address_country ≠ USA)

All USA individual fields apply, with these differences:

Field	Change
`ssn`	Not required
`immigration_status`	Required. Exactly one of: `U.S. Citizen` · `Permanent U.S. Resident` · `Lawful Permanent Resident of U.S.` · `Non-Permanent U.S. Resident` · `Non-Resident of U.S.`
`additional_info.has_us_bank_account`	`Yes` / `No`
`additional_info.has_denied_bank_account`	`Yes` / `No`

USA business (type: business, address_country: USA)

Entity identity

Field	Accepted values
`business_legal_name`	Free text
`business_type`	`limited_liability_company` · `corporation` · `general_partnership` · `limited_liability_partnership` · `sole_proprietor` · `non_profit` · `trust` · `government_organization` · `publicly_traded_company` (aliases also accepted: `llc`, `sole_prop`, `nonprofit`, `government`, `publicly_traded`, `llp`, `partnership`, `sa_de_cv`, `ltda`, `cooperative`)
`business_description`	Free text
`business_industry`	Array of NAICS-style codes, e.g. `telecommunications`, `real_estate`
`formation_date`	ISO 8601
`formation_state` · `formation_country`	`formation_country` = ISO alpha-3
`address_street` · `address_city` · `address_state` · `address_zip_code` · `address_country`	Free text; country = ISO alpha-3
`ein`	Sent inside `identifying_information`: `[{ "type": "ein", "number": "…" }]`
`identifying_information: file_business_formation`	Business formation document

Questionnaire

Field	Accepted values
`account_purpose`	`charitable_donations` · `ecommerce_retail_payments` · `investment_purposes` · `purchase_goods_and_services` · `receive_payments_for_goods_and_services` · `internal_treasury` · `third_party_money_transmission` · `operating_a_company`
`source_of_funds`	`business_loans` · `inter_company_funds` · `investment_proceeds` · `owners_capital` · `sales_of_goods_and_services` · `tax_refund` · `third_party_funds` · `treasury_reserves` · `company_funds` · `investments_loans`
`pep_status`	Boolean
`expected_monthly_volume`	`less_than_50000` · `50000_to_100000` · `100000_to_500000` · `500000_to_1000000` · `1000000_to_5000000` · `5000000_to_10000000` · `more_than_10000000`
`expected_transaction_count`	`less_than_10` · `10_to_25` · `26_to_50` · `51_to_100` · `101_to_500` · `more_than_500`

Associated persons (UBOs / directors) — associated_persons is an array; each object carries the person’s own identity:

Field	Notes
`first_name` · `last_name`	Free text
`birth_date`	ISO 8601
`email` · `nationality`	Email string · ISO alpha-3
`document_type` · `document_number`	Free text
`ssn`	Required unless the person’s `nationality` is non-US
`identifying_information: front`	Document photo
`identifying_information: back`	Document photo — required unless `document_type` = `passport`

International business (type: business, address_country ≠ USA)

All USA business fields apply, with these differences:

Field	Change
`ein`	Not required
`address_state`	Not required
`document_number` · `document_country`	Required — free text; `document_country` = ISO alpha-3
`international_entity_type`	Required — free text, e.g. `Sociedad de Responsabilidad Limitada`
`additional_info.has_us_bank_account`	`Yes` / `No`
`additional_info.has_denied_bank_account`	`Yes` / `No`
`associated_persons: document_country`	Required for international UBOs — ISO alpha-3

The two USA virtual-account products require different fields. usa-virtual-accounts and usa-virtual-accounts-act do not share an identical KYC set at version 2026-04-14. Rather than hard-coding either list, read the per-product missing_fields map on GET /v1/users/{id} and fill what it reports for the product you are creating. See For AI agents and the missing_fields example in Webhooks.

Conditional field rules

missing_fields tokens encode these conditions; send the field only when the condition holds.

Token	Rule
`ssn:unless_immigration_status:non_us_citizen`	Send `ssn` for everyone except non-US citizens
`occupation:when_employment_status:employed`	Send `occupation` (and `current_employer`) only when `employment_status` = `employed`
`income_source` (unless employed)	Send `income_source` for everyone except `employed`
`identifying_information:back:unless_doc_type:passport`	Send the ID back photo for every document type except `passport`
`identifying_information:file_proof_of_address`	Send proof of address when an EDD trigger applies

Country restrictions

All codes are ISO 3166-1 alpha-3. Rules apply to address_country unless noted.

Blocked

Users with address_country in this list are ineligible for any virtual-account product: AFG BLR MMR CAF CIV CUB COD IRN IRQ LBR LBY PRK RUS SAU SOM SDN SYR UKR YEM VEN ZWE

Enhanced due diligence (EDD)

When an EDD trigger applies, add a proof-of-address document (identifying_information: file_proof_of_address). Individuals (53 countries) — triggered when address_country is in: DZA AGO ARM AZE BHS BHR BGD BMU BOL VGB BRN BFA KHM CMR CXR CCK CRI CYP EGY SLV GIB GRC GTM GGY HTI HND IDN IMN JEY JOR KAZ KEN KWT LBN LIE MYS MCO MNG MOZ NIC NGA OMN PNG PRY PHL ZAF LKA THA TTO TUN UGA UZB VNM Businesses (51 countries) — the same list minus GTM and CCK. For businesses, proof of address is required if any one of these is true:

address_country is in the business EDD list OR formation_country is in the business EDD list OR the company was formed within the last 180 days.

Example payloads

Complete POST /v1/users bodies for each category. Adapt the values; document content fields take base64-encoded images.

{
  "type": "individual",
  "first_name": "Ana",
  "last_name": "García",
  "birth_date": "1990-04-22",
  "email": "ana@example.com",
  "phone": "+15551234567",
  "nationality": "USA",
  "address_street": "123 Main St",
  "address_city": "Austin",
  "address_state": "TX",
  "address_zip_code": "78701",
  "address_country": "USA",
  "document_type": "drivers_license",
  "document_number": "DL-987654321",
  "document_country": "USA",
  "employment_status": "employed",
  "occupation": "Software Engineer",
  "current_employer": "Acme Corp",
  "account_purpose": "receive_payments",
  "source_of_funds": "salary",
  "expected_monthly_volume": "10000_to_49999",
  "expected_transaction_count": "11_to_50",
  "pep_status": false,
  "identifying_information": [
    { "type": "ssn", "number": "XXX-XX-XXXX" },
    { "type": "front", "content": "<base64>" },
    { "type": "back",  "content": "<base64>" }
  ]
}

Create a user — API reference — the endpoint, full schema, and live “Try it”.
For AI agents — eligible_products / missing_fields, conditional tokens, getting a user to VERIFIED in sandbox.
Webhooks — the user.created payload with the per-product missing_fields map.
Known limitations — the auto-reject gotcha and status vs verification_status.

​The four user categories

​Minimum to create

​Required fields by category

​Shared identity fields

​Conditional field rules

​Country restrictions

​Blocked

​Enhanced due diligence (EDD)

​Example payloads

​Related

The four user categories

Minimum to create

Required fields by category

Shared identity fields

Conditional field rules

Country restrictions

Blocked

Enhanced due diligence (EDD)

Example payloads

Related