Create a user
Creates a business under your account and starts its verification.
Two ways to verify, set with verification_mode:
automatic— the default. Verification runs now and you receiveuser.*webhooks (see Webhooks).verification_link— Kira drops every other field you sent and answers with a hosted form for someone to fill in.
Headers
Version applied to this request. It wins over your account's pinned version — see Versioning.
"2026-06-01"
A UUID you generate for this request. Send a fresh one per business you create.
Reusing a key with the same body returns the original result instead of creating a second business. Reusing it with a different body answers 409.
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
Body
Must be business. Individuals created before this endpoint stopped accepting them keep working, and still read as type: individual.
business The registered legal name of the business.
1The business's email address.
How this business gets verified.
See User values for what each value means.
automatic, verification_link Which banks this business plans to use. This records intent only — authorizing an account for a bank is separate, and lives in your account's configuration.
Where the hosted verification form redirects after completion. Used only with verification_mode: verification_link.
The locale for the hosted verification form. It only matters when verification_mode is verification_link.
See User values for the accepted values.
en, es The legal structure of the business.
See User values for the accepted values.
Accepted here, but not returned in the user object — do not expect to read it back.
Trade name, if different from the legal name. Accepted here, but not returned in the user object — do not expect to read it back.
The name the business trades under. Required to verify a business. A business with no trade name sends its legal name.
Accepted here, but not returned in the user object — do not expect to read it back.
Short description of what the business does. Accepted here, but not returned in the user object — do not expect to read it back.
The industry the business works in, as a NAICS subsector slug — telecommunications, real_estate, construction_of_buildings.
See User values for the full list. Send one industry. A second is refused with a 400.
Accepted here, but not returned in the user object — do not expect to read it back.
1Business website URL.
Ignored on create — new users always start as CREATED.
Your own reference ID for this user (stored as partnerUserId).
Phone in E.164 format, e.g. +14155551234. Spaces and dashes are sanitized before validation.
Date the entity was formed, YYYY-MM-DD.
^\d{4}-\d{2}-\d{2}$State or province of formation.
Country of formation as ISO alpha-3. The bank's verifier records it as the country the business is registered in. The address country never stands in for it.
3Registered (legal) business address.
Physical operating address, if different from registered.
Accepted here, but not returned in the user object — do not expect to read it back.
Street address (≤ 70 chars). Flat (V2) address form.
70Apartment, suite, or unit (≤ 70 chars).
70City.
State or province (US state for USA users).
ZIP or postal code.
Country as ISO alpha-3. With type, selects the user category; users in restricted countries are not VA-eligible.
Authorized representative — given name.
Authorized representative — family name.
Representative job title.
Representative date of birth, YYYY-MM-DD. On update the field is named representative_birth_date.
^\d{4}-\d{2}-\d{2}$Representative SSN (US businesses).
US business tax ID. May also be sent inside identifying_information as { "type": "ein", "number": "…" }.
Brazilian business tax ID.
Mexican tax ID.
Primary government document type (e.g. passport, drivers_license).
Primary government document number.
Issuing country of the primary document, ISO alpha-3.
Whether the user is a Politically Exposed Person.
Terms-of-service version the user accepted. Kira stamps tos_accepted_at on receipt.
How much the business expects to receive in payments in a month, as a bucket.
See User values for the buckets.
less_than_50000, 50000_to_100000, 100000_to_500000, 500000_to_1000000, 1000000_to_5000000, 5000000_to_10000000, more_than_10000000 How much the business expects to move in a month.
See User values for the buckets.
less_than_50000, 50000_to_100000, 100000_to_500000, 500000_to_1000000, 1000000_to_5000000, 5000000_to_10000000, more_than_10000000 How many payments the business expects to make in a month.
See User values for the buckets.
less_than_10, 10_to_25, 26_to_50, 51_to_100, 101_to_500, more_than_500 Whether ownership flows through intermediary entities. Accepted here, but not returned in the user object — do not expect to read it back.
What the business will use the account for.
See User values for the accepted values.
Accepted here, but not returned in the user object — do not expect to read it back.
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 Where the money the business moves comes from.
See User values for the accepted values.
Accepted here, but not returned in the user object — do not expect to read it back.
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 A KYB attestation: whether the business operates in a high-risk industry.
Yes, No A KYB attestation: whether the business is a non-bank financial institution or virtual-asset service provider.
Yes, No A KYB attestation: whether the business has relevant legal history.
Yes, No The countries this business expects to transact with, as ISO 3166-1 codes.
Some virtual-account routes need it. When it is absent the gap is reported in missing_fields — Kira never guesses a market you did not declare.
1How a corporation is taxed (ACT route).
How an LLC is taxed (ACT route).
Free-text legal entity type for non-US businesses (e.g. Sociedad de Responsabilidad Limitada).
Free-form string map. International users must include has_us_bank_account and has_denied_bank_account (Yes/No, case-sensitive; lowercase is not accepted by ACT provisioning).
Tax IDs and government documents. Each entry requires type and issuing_country.
Legacy flat document array. Prefer identifying_information[].documents[].
The people behind the business — owners, people in control, and authorized signers. Kira matches them by email.
A business needs at least one beneficial owner. That is a person with has_ownership: true and an ownership_percentage at or above the threshold of the bank that verifies the business: 25 when the business requests jp_morgan, 10 otherwise. Without that, verification does not start and associated_persons:beneficial_owner shows up in missing_fields. A business that is already verified is not re-blocked by this.
A business needs one person who signs. That is a person with is_signer: true. They represent the business in verification. Without one, associated_persons:signer shows up in missing_fields. A business verified through a link declares its representative there instead. A business that is already verified is not re-blocked by this.
The representative_* fields are stored as data. They never add a person to the business.
An owner below that threshold who neither signs nor controls the business is not sent for verification, and nothing is asked of them.
The three roles are independent, and one person can hold all of them.
Your key-value pairs. ≤ 50 keys; key 1–40 chars with no [ or ]; value ≤ 500 chars. Kira can additionally configure client-level default metadata for your account; defaults are merged in at create time (your keys win on conflict), so the stored and returned metadata may include keys you did not send.
Optional partner-supplied KYC session ID.
Response
The business was created. Verification has not necessarily started — read verification_triggered and missing_fields.
The id of the business you just created. Use it on every other call.
Always business.
Starts at CREATED. See User values.
Starts at unverified. See User values.
ISO 8601.
ISO 8601.
The mode this business was created with.
The hosted form to send the business to. Only in verification_link mode.
Until someone completes it, the other fields echo placeholders — nationality: "---", birth_date: "1900-01-01", an empty address. Read missing_fields, not those values.
The key-value pairs you sent.
ISO alpha-3.
A postal address.
Whether verification started. It is false while any product still reports missing fields.
What the business can use, product by product. Every entry is eligible: false until verification passes.
The gaps that remain, grouped by product code, plus a general key holding every token once.
A product with nothing outstanding is left out of the map, so it can come back with only general, or empty.
The records you sent, with the stored files.
The people you sent. Fields Kira does not keep are dropped from the echo.
Non-fatal problems with the documents you sent. Absent when there are none.