> ## Documentation Index > Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a user > Creates an end client (your user) and **starts identity verification** — KYC for `individual`, KYB for `business`. The required field set depends on `type` (`individual` | `business`) and `address_country` (ISO **alpha-3**, e.g. `USA`, `MEX`). See [Creating users](/guides/creating-users) for the full per-category field tables, conditional rules, and country restrictions. **Required to create:** individuals need `type`, `first_name`, `last_name`, `email`; businesses need `type`, `business_legal_name`, `email`. A bare payload returns `201`, but the user will not be product-eligible. The **`Idempotency-Key` header is required** and must be a UUID; reusing a key with a different body returns `409`. **Enums differ by `type`.** `account_purpose` accepts **14** values for individuals and **8** (different) values for businesses; `source_of_funds`, `expected_monthly_volume`, and `expected_transaction_count` likewise differ between individuals and businesses. `expected_monthly_payments` is a free-form string on this endpoint — use `expected_monthly_volume` + `expected_transaction_count` for bucketed values. Any out-of-set value → `400 invalid_enum_value`. **Verification modes** (`verification_mode`): - `automatic` (default) — verification runs on create and you receive `user.*` webhooks. Send `source_of_funds` and the full category field set. - `verification_link` — every other field is stripped and a hosted KYC URL is returned as `verification_link`. Pass `redirect_uri` to control the post-completion redirect and `language` (`en`/`es`) for the form locale. The created user **echoes placeholder values** for the stripped fields (`nationality: "---"`, `birth_date: "1900-01-01"`, empty `residential_address`) until the hosted flow completes — treat `eligible_products[].missing_fields` as the authoritative outstanding-fields signal, not the echoed field values. **Documents** (`identifying_information[].documents[].file`) accept a base64 data URI (JPEG/PNG/PDF) or — on version `2026-04-14`+ — an `https://` URL (`http://` is rejected). A two-sided ID (any type except `passport`/`visa`) that includes a `front` must also include a `back`. **The whole request body is capped at 10 MB** and inline base64 counts against it (≈ +33% overhead), so prefer the `https://` URL form for large files — it's fetched asynchronously, doesn't count toward the body limit, and accepts files up to 30 MB each. **Sandbox verification behavior:** identity verification triggers automatically once the user is complete for at least one product (`verification_triggered: true`) and the sandbox approves within seconds — no manual step. An incomplete user is NOT rejected: verification does not trigger and the user stays `CREATED` with the gaps listed in `missing_fields`. A terminal `REJECTED` means the provider evaluated the submitted data and declined it (`user.verification.failed` webhook; `verification_status` may still read `unverified` — gate on `status`). The rejection reason is delivered ONLY in the `user.verification.failed` webhook (`data.reasons[]`) — `GET /v1/users/{id}` never exposes it. A data rejection is distinct from a verification-**provider call failure** (network / 5xx / timeout reaching the provider): a call failure is a retryable system error — the user stays non-terminal (`VERIFYING`), no `user.verification.failed` fires, and the transition surfaces via `user.status_changed`. **Response (`201`)** returns the user plus `verification_triggered`, `eligible_products[]`, `missing_fields` (per-product field tokens; populated once verification has run), `verification_link` (link mode only), and `warnings[]` (non-fatal document-upload issues). {/* version-stamp:start — generated by scripts/stamp-versions.ts, do not edit */} Changed in this version. {/* version-stamp:end */} ## OpenAPI ````yaml /openapi/kira-api.2026-04-14.json post /v1/users openapi: 3.1.0 info: title: Kira API version: '2026-04-14' description: >- REST API for users, KYC/KYB verification, virtual accounts, payouts, recipients, and webhooks. Every request requires an `x-api-key` header and a bearer access token (see Authentication). Pin your account to version `2026-04-14` before integrating. contact: name: Kira API Support email: support@kirafin.ai servers: - url: https://api.balampay.com description: Production - url: https://api.balampay.com/sandbox description: Sandbox security: - bearerAuth: [] apiKeyAuth: [] tags: - name: Authentication - name: Versioning - name: Users - name: Virtual Accounts - name: Quotations - name: Payouts - name: Recipients - name: Reference paths: /v1/users: post: tags: - Users summary: Create a user description: >- Creates an end client (your user) and **starts identity verification** — KYC for `individual`, KYB for `business`. The required field set depends on `type` (`individual` | `business`) and `address_country` (ISO **alpha-3**, e.g. `USA`, `MEX`). See [Creating users](/guides/creating-users) for the full per-category field tables, conditional rules, and country restrictions. **Required to create:** individuals need `type`, `first_name`, `last_name`, `email`; businesses need `type`, `business_legal_name`, `email`. A bare payload returns `201`, but the user will not be product-eligible. The **`Idempotency-Key` header is required** and must be a UUID; reusing a key with a different body returns `409`. **Enums differ by `type`.** `account_purpose` accepts **14** values for individuals and **8** (different) values for businesses; `source_of_funds`, `expected_monthly_volume`, and `expected_transaction_count` likewise differ between individuals and businesses. `expected_monthly_payments` is a free-form string on this endpoint — use `expected_monthly_volume` + `expected_transaction_count` for bucketed values. Any out-of-set value → `400 invalid_enum_value`. **Verification modes** (`verification_mode`): - `automatic` (default) — verification runs on create and you receive `user.*` webhooks. Send `source_of_funds` and the full category field set. - `verification_link` — every other field is stripped and a hosted KYC URL is returned as `verification_link`. Pass `redirect_uri` to control the post-completion redirect and `language` (`en`/`es`) for the form locale. The created user **echoes placeholder values** for the stripped fields (`nationality: "---"`, `birth_date: "1900-01-01"`, empty `residential_address`) until the hosted flow completes — treat `eligible_products[].missing_fields` as the authoritative outstanding-fields signal, not the echoed field values. **Documents** (`identifying_information[].documents[].file`) accept a base64 data URI (JPEG/PNG/PDF) or — on version `2026-04-14`+ — an `https://` URL (`http://` is rejected). A two-sided ID (any type except `passport`/`visa`) that includes a `front` must also include a `back`. **The whole request body is capped at 10 MB** and inline base64 counts against it (≈ +33% overhead), so prefer the `https://` URL form for large files — it's fetched asynchronously, doesn't count toward the body limit, and accepts files up to 30 MB each. **Sandbox verification behavior:** identity verification triggers automatically once the user is complete for at least one product (`verification_triggered: true`) and the sandbox approves within seconds — no manual step. An incomplete user is NOT rejected: verification does not trigger and the user stays `CREATED` with the gaps listed in `missing_fields`. A terminal `REJECTED` means the provider evaluated the submitted data and declined it (`user.verification.failed` webhook; `verification_status` may still read `unverified` — gate on `status`). The rejection reason is delivered ONLY in the `user.verification.failed` webhook (`data.reasons[]`) — `GET /v1/users/{id}` never exposes it. A data rejection is distinct from a verification-**provider call failure** (network / 5xx / timeout reaching the provider): a call failure is a retryable system error — the user stays non-terminal (`VERIFYING`), no `user.verification.failed` fires, and the transition surfaces via `user.status_changed`. **Response (`201`)** returns the user plus `verification_triggered`, `eligible_products[]`, `missing_fields` (per-product field tokens; populated once verification has run), `verification_link` (link mode only), and `warnings[]` (non-fatal document-upload issues). operationId: post_v1-users parameters: - in: header name: X-Api-Version required: false description: >- Optional. The date-versioned API version to apply for this request (e.g. `2026-04-14`). When sent it always wins, even over your pinned account default. When omitted, the API uses your account's pinned version if set, otherwise a baseline default. schema: type: string example: '2026-04-14' - in: header name: Idempotency-Key required: true schema: type: string format: uuid example: '{{idempotency_key}}' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest' examples: create-user-individual-intl-act-route: summary: Create User — Individual INTL (ACT route) value: type: individual verification_mode: automatic first_name: Maria last_name: Gonzalez birth_date: '1990-05-15' email: maria.test+1782336813@example.com phone: '+525512345678' nationality: MEX address_street: Av. Reforma 123 address_city: Ciudad de Mexico address_state: CDMX address_zip_code: '06600' address_country: MEX document_type: passport document_number: G12345678 document_country: MEX immigration_status: Non-Resident of U.S. employment_status: employed current_employer: Self occupation: Software Engineer account_purpose: receive_payments source_of_funds: salary identifying_information: - type: passport issuing_country: MEX number: G12345678 expiration: '2030-05-15' documents: - type: front file: data:image/jpeg;base64,PLACEHOLDER additional_info: has_us_bank_account: 'No' has_denied_bank_account: 'No' create-user-individual-usa-act-route: summary: Create User — Individual USA (ACT route) value: type: individual verification_mode: automatic first_name: John last_name: Doe birth_date: '1985-03-22' email: john.test+1782336813@example.com phone: '+15551234567' nationality: USA address_street: 123 Main St address_city: San Francisco address_state: CA address_zip_code: '94105' address_country: USA document_type: drivers_license document_number: D1234567 document_country: USA ssn: 111-11-1111 immigration_status: U.S. Citizen employment_status: employed current_employer: Acme Inc occupation: Engineer account_purpose: receive_payments source_of_funds: salary identifying_information: - type: drivers_license issuing_country: USA number: D1234567 documents: - type: front file: data:image/jpeg;base64,PLACEHOLDER - type: back file: data:image/jpeg;base64,PLACEHOLDER - type: ssn issuing_country: USA number: 111-11-1111 additional_info: has_us_bank_account: 'Yes' has_denied_bank_account: 'No' create-user-individual-usa-portage-route-with-documents: summary: Create User — Individual USA (Portage route, with documents) value: type: individual verification_mode: automatic first_name: Sarah last_name: Johnson birth_date: '1988-07-22' email: sarah.test+1782336813@example.com phone: '+14155551234' nationality: USA address_street: 456 Market Street address_city: San Francisco address_state: CA address_zip_code: '94103' address_country: USA document_type: drivers_license document_number: D9876543 document_country: USA ssn: 111-11-1111 immigration_status: U.S. Citizen employment_status: employed current_employer: Self occupation: Engineer account_purpose: receive_payments source_of_funds: salary identifying_information: - type: drivers_license issuing_country: USA number: D9876543 documents: - type: front file: data:image/jpeg;base64,PLACEHOLDER - type: back file: data:image/jpeg;base64,PLACEHOLDER - type: ssn issuing_country: USA number: 111-11-1111 additional_info: has_us_bank_account: 'Yes' has_denied_bank_account: 'No' create-user-individual-intl-portage-route-with-documents: summary: Create User — Individual INTL (Portage route, with documents) value: type: individual verification_mode: automatic first_name: Carlos last_name: Rodriguez birth_date: '1992-03-15' email: carlos.test+1782336813@example.com phone: '+525587654321' nationality: MEX address_street: Calle Roma 50 address_city: Ciudad de Mexico address_state: CDMX address_zip_code: '06700' address_country: MEX document_type: passport document_number: P98765432 document_country: MEX immigration_status: Non-Resident of U.S. employment_status: employed current_employer: Self occupation: Engineer account_purpose: receive_payments source_of_funds: salary identifying_information: - type: passport issuing_country: MEX number: P98765432 expiration: '2032-03-15' documents: - type: front file: data:image/jpeg;base64,PLACEHOLDER additional_info: has_us_bank_account: 'No' has_denied_bank_account: 'No' create-user-business-usa: summary: Create User — Business USA value: type: business verification_mode: automatic business_legal_name: Acme Trading LLC doing_business_as: Acme business_type: llc business_industry: - merchant_wholesalers_nondurable_goods business_description: Wholesale distribution of packaged goods formation_date: '2020-01-15' formation_country: USA email: ops.acme+1782336813@example.com phone: '+14155559999' address_street: 1 Market Street address_city: San Francisco address_state: CA address_zip_code: '94105' address_country: USA ein: 12-3456789 account_purpose: receive_payments_for_goods_and_services source_of_funds: sales_of_goods_and_services high_risk_industries: 'No' is_nbfi_vasp: 'No' business_legal_history: 'No' pep_status: false expected_monthly_volume: less_than_50000 expected_transaction_count: less_than_10 identifying_information: - type: business_formation issuing_country: USA documents: - type: file_business_formation file: data:application/pdf;base64,PLACEHOLDER - type: file_certificate_of_good_standing file: data:application/pdf;base64,PLACEHOLDER - type: file_portfolio_statement file: data:application/pdf;base64,PLACEHOLDER - type: file_board_minutes file: data:application/pdf;base64,PLACEHOLDER associated_persons: - has_ownership: true ownership_percentage: 100 first_name: Alice last_name: Smith birth_date: '1980-05-15' email: alice+1782336813@example.com nationality: USA document_type: passport document_number: US11111111 identifying_information: - type: ssn issuing_country: USA number: 222-22-2222 - type: passport issuing_country: USA number: US11111111 documents: - type: front file: data:image/jpeg;base64,PLACEHOLDER create-user-business-intl: summary: Create User — Business INTL value: type: business verification_mode: automatic business_legal_name: Globex SA de CV doing_business_as: Globex business_type: corporation business_industry: - merchant_wholesalers_nondurable_goods business_description: Wholesale distribution across Latin America formation_date: '2018-06-01' formation_country: MEX email: ops.globex+1782336813@example.com phone: '+525555550000' address_street: Av. Insurgentes 200 address_city: Ciudad de Mexico address_state: CDMX address_zip_code: '06600' address_country: MEX document_number: RFC-GLO180601AB1 document_country: MEX international_entity_type: corporation account_purpose: receive_payments_for_goods_and_services source_of_funds: sales_of_goods_and_services high_risk_industries: 'No' is_nbfi_vasp: 'No' business_legal_history: 'No' pep_status: false expected_monthly_volume: less_than_50000 expected_transaction_count: less_than_10 additional_info: has_us_bank_account: 'No' has_denied_bank_account: 'No' identifying_information: - type: business_formation issuing_country: MEX documents: - type: file_business_formation file: data:application/pdf;base64,PLACEHOLDER - type: file_certificate_of_good_standing file: data:application/pdf;base64,PLACEHOLDER - type: file_portfolio_statement file: data:application/pdf;base64,PLACEHOLDER - type: file_board_minutes file: data:application/pdf;base64,PLACEHOLDER associated_persons: - has_ownership: true ownership_percentage: 100 first_name: Pedro last_name: Martinez birth_date: '1975-11-20' email: pedro+1782336813@example.com nationality: MEX document_type: passport document_number: P55555555 document_country: MEX identifying_information: - type: passport issuing_country: MEX number: P55555555 documents: - type: front file: data:image/jpeg;base64,PLACEHOLDER create-user-individual-usa-document-via-url: summary: >- Create User — Individual USA (document supplied by HTTPS URL, 2026-04-14+) description: >- Same as the Portage-with-documents example, but each `documents[].file` is a hosted `https://` URL instead of an inline base64 data URI. Kira downloads each file asynchronously (host must be on the client's allowed-domains list), so the document starts as `download_status: pending`. Download failures surface in `warnings[]` and a `user.document.download.failed` webhook — they do not fail the call. URL documents require API version `2026-04-14` or later. value: type: individual verification_mode: automatic first_name: Sarah last_name: Johnson birth_date: '1988-07-22' email: sarah.url@example.com phone: '+14155551234' nationality: USA address_street: 456 Market Street address_city: San Francisco address_state: CA address_zip_code: '94103' address_country: USA document_type: drivers_license document_number: D9876543 document_country: USA ssn: 111-11-1111 immigration_status: U.S. Citizen employment_status: employed current_employer: Self occupation: Engineer account_purpose: receive_payments source_of_funds: salary identifying_information: - type: drivers_license issuing_country: USA number: D9876543 documents: - type: front file: https://api.aiprise.com/documents/dl-front.jpg - type: back file: https://api.aiprise.com/documents/dl-back.jpg - type: ssn issuing_country: USA number: 111-11-1111 additional_info: has_us_bank_account: 'Yes' has_denied_bank_account: 'No' responses: '201': description: Created. content: application/json: schema: $ref: '#/components/schemas/CreateUserResponse' '400': description: Validation error. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- Conflict — the `Idempotency-Key` was reused with a different request body. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] apiKeyAuth: [] components: schemas: CreateUserRequest: oneOf: - type: object properties: type: type: string enum: - individual description: >- Discriminator: `individual` (KYC) or `business` (KYB). Selects the required fields and which enum sets apply. verification_mode: type: string enum: - automatic - verification_link description: >- `automatic` (default) runs verification on create and emits `user.*` webhooks. `verification_link` returns a hosted KYC URL and strips every other field. capabilities: type: object description: >- Per-subclient bank *intent* — records which bank(s) this subclient plans to use, distinct from bank-account authorization (which lives in your account's own configuration). Optional; omit it to use the standard verification path. properties: requested_banks: type: array items: type: string enum: - portage - slovak_savings_bank - austin_capital_trust description: Bank slugs this subclient intends to use. redirect_uri: type: string format: uri description: >- Where the hosted verification form redirects after completion. Used only with `verification_mode: verification_link`. language: type: string enum: - en - es description: >- Locale for the hosted verification form: `en` or `es`. Used only with `verification_mode: verification_link`. first_name: type: string minLength: 1 description: Given name. Required for individuals. last_name: type: string minLength: 1 description: Family name. Required for individuals. email: type: string format: email description: Email address. Required for all users. middle_name: type: string description: Middle name. phone: type: string description: >- Phone in E.164 format, e.g. `+14155551234`. Spaces and dashes are sanitized before validation. birth_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Date of birth, `YYYY-MM-DD`. The user must be at least 18 years old. nationality: type: string minLength: 3 maxLength: 3 description: >- Nationality as an ISO 3166-1 **alpha-3** code (e.g. `USA`, `MEX`). gender: type: string enum: - male - female - other description: One of `male`, `female`, `other`. status: type: string enum: - active - inactive - suspended default: active description: Ignored on create — new users always start as `CREATED`. external_id: type: string description: Your own reference ID for this user (stored as `partnerUserId`). residential_address: type: object properties: street_line_1: type: string minLength: 1 street_line_2: type: string city: type: string minLength: 1 subdivision: type: string postal_code: type: string country: type: string minLength: 3 maxLength: 3 description: >- Country as an ISO 3166-1 alpha-3 code, exactly 3 letters (e.g. `USA`, `MEX`, `BRA`). A 2-letter value (e.g. `US`) is rejected with "Must be a 3-letter country code". The same alpha-3 format applies to every other country field on this schema (`address_country`, `formation_country`, `document_country`, and the `associated_persons[]` address/document country fields). description: >- Structured residential address (V1). You may instead use the flat `address_*` fields. address_street: type: string maxLength: 70 description: Street address (≤ 70 chars). Flat (V2) address form. address_street_2: type: string maxLength: 70 description: Apartment, suite, or unit (≤ 70 chars). address_city: type: string description: City. address_state: type: string description: State or province (US state for USA users). address_zip_code: type: string description: ZIP or postal code. address_country: type: string description: >- Country as ISO **alpha-3**. With `type`, selects the user category; users in restricted countries are not VA-eligible. identifying_information: type: array items: type: object properties: type: type: string enum: - passport - national_id - drivers_license - matriculate_id - military_id - permanent_residency_id - state_or_provincial_id - visa - ssn - itin - ein - curp - rfc - cpf - cnpj - tin - nuip - nit - tax_id - proof_of_address - business_formation - source_of_wealth description: >- Kind of identity document or tax identifier for this person. The type value is validated against a fixed list. A government-ID / tax-ID gap does not reject the request (an entry with no documents[] photo or no `number` is still accepted and reported in the response's `missing_fields`), but an unresolved gap blocks KYC/KYB verification from triggering for a not-yet-verified user, so it must be resolved before that user can verify. Government photo IDs (pair with a `documents[]` photo, e.g. `front`/`back`): `passport`, `national_id`, `drivers_license`, `matriculate_id`, `military_id`, `permanent_residency_id`, `state_or_provincial_id`, `visa`. Tax/identity numbers (send the value in `number`): `ssn` (US Social Security Number), `itin` (US Individual Taxpayer ID), `ein` (US Employer ID), `curp` (Mexico), `rfc` (Mexico tax ID), `cpf` (Brazil), `cnpj` (Brazil business), `tin` (generic), `nuip` (Colombia), `nit` (Colombia business), `tax_id` (generic). Supporting documents (attach a file in `documents[]`): `proof_of_address`, `business_formation`, `source_of_wealth`. issuing_country: type: string minLength: 3 maxLength: 3 description: Issuing country, ISO **alpha-3**. Required. number: type: string description: Identifier number (for tax IDs or document numbers). description: type: string expiration: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Expiry date, `YYYY-MM-DD`. documents: type: array items: type: object properties: type: type: string enum: - front - back - selfie - file_proof_of_address - file_business_formation - file_source_of_wealth - file_ein_letter - file_bylaws - file_corporate_resolution - file_certificate_of_registration - file_certificate_of_good_standing - file_board_minutes - file_portfolio_statement - file_fatca - file_company_fiscal_registration description: >- Role of this file within the parent identifying-information entry. Government-ID entries must include **both** `front` and `back` — single-sided types (`passport`, `visa`) may send only `front`. `selfie` is a face-match photo: send it in `documents[]` alongside the ID and Kira submits both to the identity provider, which matches the selfie against the ID portrait; on a pass the resulting biometric verification report is attached to the user automatically, with no interactive session required. (For a higher-assurance check that also proves liveness, use `POST /v1/users/{user_id}/liveness-link` instead.) The `file_*` roles each carry the matching supporting document (`file_proof_of_address` a proof of residence — for individuals and business owners alike — plus formation docs, EIN letter, bylaws, corporate resolution, certificate of registration / good standing, board minutes, portfolio statement). `file_fatca` carries the signed tax self-certification (W-9 or W-8BEN) — Kira does not generate this for you, because the form's federal tax classification cannot be derived from the data you send us — and `file_company_fiscal_registration` the tax-registration certificate. Which of these a given user needs depends on the product: read `missing_fields` for the product you are opening rather than uploading the whole set. file: type: string description: >- Document content. **Two forms are accepted:** - **Base64-encoded file** — a data URI of the form `data:;base64,`. Supported MIME types: `image/jpeg`, `image/png`, `application/pdf`. The bytes are uploaded to storage synchronously while the request runs. - **HTTPS URL** — a link to a hosted file (`https://…`; plain `http://` is rejected on every version). Accepted only on API version `2026-04-14` or later. Kira fetches the file **asynchronously**: the host must be on the client's allowed-domains list (defaults to `aiprise.com` / `api.aiprise.com` when none is configured) and the file is re-checked (MIME type + a 30 MB per-file size cap) before it is stored. While the fetch is in flight the stored document carries `download_status: "pending"`; a permanent failure emits a `user.document.download.failed` webhook and is reported in the response `warnings[]` — it never fails the create/update call. **Request-body cap (10 MB):** the whole request is limited to 10 MB and inline base64 counts against it (≈ +33% overhead). For large files prefer the `https://` URL form: it is fetched asynchronously, does NOT count toward the body limit, and accepts files up to 30 MB each. pattern: >- ^(data:(image/jpeg|image/png|application/pdf);base64,.+|https://.+)$ examples: - data:image/jpeg;base64,/9j/4AAQSkZJRg... - >- https://api.aiprise.com/documents/passport-front.jpg description: type: string required: - type - file description: Document images or files for this entry. required: - type - issuing_country description: >- Tax IDs and government documents. Each entry requires `type` and `issuing_country`. pep_status: type: boolean description: Whether the user is a Politically Exposed Person. tos_accepted_version: type: string description: >- Terms-of-service version the user accepted. Kira stamps `tos_accepted_at` on receipt. source_of_funds: type: string enum: - salary - self_employment_income - investment_proceeds - savings_inheritance_gift - gifts - inheritance - investments_loans - pension_retirement - sale_of_assets_real_estate - savings - someone_elses_funds description: >- Origin of funds. The accepted enum **differs for individuals vs businesses**. account_purpose: type: string enum: - 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 description: >- Intended account use. **14** values for individuals, **8** (different) values for businesses. expected_monthly_payments: type: string description: >- Free-form string. Prefer `expected_monthly_volume` + `expected_transaction_count` for bucketed values. expected_monthly_volume: type: string enum: - less_than_10000 - 10000_to_49999 - 50000_to_199999 - 200000_to_999999 - 1000000_or_more description: >- Expected monthly volume bucket. Buckets differ for individuals vs businesses. expected_transaction_count: type: string enum: - 1_to_10 - 11_to_50 - 51_to_200 - more_than_200 description: >- Expected monthly transaction-count bucket. Buckets differ for individuals vs businesses. employment_status: type: string enum: - employed - self_employed - unemployed - retired - student description: >- One of `employed`, `self_employed`, `unemployed`, `retired`, `student`. occupation: type: string description: >- Occupation. Required (for eligibility) when `employment_status = employed`. current_employer: type: string description: >- Employer. Required (for eligibility) when `employment_status = employed`. income_source: type: string description: >- Income source. Required (for eligibility) unless `employment_status = employed`. documents: type: array items: type: object properties: type: type: string minLength: 1 description: >- Document role/type. Free-form on this legacy array (e.g. `front`, `file_proof_of_address`). Prefer `identifying_information[].documents[]`, which validates the role against a fixed set. file: type: string description: >- Document content. **Two forms are accepted:** - **Base64-encoded file** — a data URI of the form `data:;base64,`. Supported MIME types: `image/jpeg`, `image/png`, `application/pdf`. The bytes are uploaded to storage synchronously while the request runs. - **HTTPS URL** — a link to a hosted file (`https://…`; plain `http://` is rejected on every version). Accepted only on API version `2026-04-14` or later. Kira fetches the file **asynchronously**: the host must be on the client's allowed-domains list (defaults to `aiprise.com` / `api.aiprise.com` when none is configured) and the file is re-checked (MIME type + a 30 MB per-file size cap) before it is stored. While the fetch is in flight the stored document carries `download_status: "pending"`; a permanent failure emits a `user.document.download.failed` webhook and is reported in the response `warnings[]` — it never fails the create/update call. **Request-body cap (10 MB):** the whole request is limited to 10 MB and inline base64 counts against it (≈ +33% overhead). For large files prefer the `https://` URL form: it is fetched asynchronously, does NOT count toward the body limit, and accepts files up to 30 MB each. pattern: >- ^(data:(image/jpeg|image/png|application/pdf);base64,.+|https://.+)$ examples: - data:image/jpeg;base64,/9j/4AAQSkZJRg... - https://api.aiprise.com/documents/passport-front.jpg file_name: type: string description: type: string required: - type - file description: >- Legacy flat document array. Prefer `identifying_information[].documents[]`. immigration_status: type: string description: >- Exact string, e.g. `U.S. Citizen`, `Permanent U.S. Resident`, `Non-Resident of U.S.` Required for international individuals. government_document_type: type: string additional_info: type: object properties: has_us_bank_account: type: string enum: - 'Yes' - 'No' has_denied_bank_account: type: string enum: - 'Yes' - 'No' additionalProperties: type: string description: >- 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). metadata: type: object additionalProperties: type: string maxLength: 500 description: >- 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. kyc_id: type: string description: Optional partner-supplied KYC session ID. required: - type - first_name - last_name - email - type: object properties: type: type: string enum: - business description: >- Discriminator: `individual` (KYC) or `business` (KYB). Selects the required fields and which enum sets apply. verification_mode: type: string enum: - automatic - verification_link description: >- `automatic` (default) runs verification on create and emits `user.*` webhooks. `verification_link` returns a hosted KYC URL and strips every other field. capabilities: type: object description: >- Per-subclient bank *intent* — records which bank(s) this subclient plans to use, distinct from bank-account authorization (which lives in your account's own configuration). Optional; omit it to use the standard verification path. properties: requested_banks: type: array items: type: string enum: - portage - slovak_savings_bank - austin_capital_trust description: Bank slugs this subclient intends to use. redirect_uri: type: string format: uri description: >- Where the hosted verification form redirects after completion. Used only with `verification_mode: verification_link`. language: type: string enum: - en - es description: >- Locale for the hosted verification form: `en` or `es`. Used only with `verification_mode: verification_link`. business_legal_name: type: string minLength: 1 description: Registered legal name. Required for businesses. email: type: string format: email description: Email address. Required for all users. business_type: type: string enum: - limited_liability_company - corporation - general_partnership - limited_liability_partnership - sole_proprietor - non_profit - trust - government_organization - publicly_traded_company - llc - sole_prop - nonprofit - government - publicly_traded - llp - partnership - sa_de_cv - ltda - cooperative description: >- Legal structure. Deprecated aliases (e.g. `llc`) are accepted and mapped to canonical values. business_trade_name: type: string description: Trade name, if different from the legal name. doing_business_as: type: string description: DBA name. business_description: type: string description: Short description of what the business does. business_industry: type: array items: type: string enum: - crop_production - animal_production - forestry_logging - fishing_hunting_trapping - support_activities_agriculture_forestry - oil_gas_extraction - mining_except_oil_gas - support_activities_mining - utilities - construction_of_buildings - heavy_civil_engineering_construction - specialty_trade_contractors - food_manufacturing - beverage_tobacco_product_manufacturing - textile_mills - textile_product_mills - apparel_manufacturing - leather_allied_product_manufacturing - wood_product_manufacturing - paper_manufacturing - printing_related_support_activities - petroleum_coal_products_manufacturing - chemical_manufacturing - plastics_rubber_products_manufacturing - nonmetallic_mineral_product_manufacturing - primary_metal_manufacturing - fabricated_metal_product_manufacturing - machinery_manufacturing - computer_electronic_product_manufacturing - electrical_equipment_appliance_component_manufacturing - transportation_equipment_manufacturing - furniture_related_product_manufacturing - miscellaneous_manufacturing - merchant_wholesalers_durable_goods - merchant_wholesalers_nondurable_goods - wholesale_electronic_markets_agents_brokers - motor_vehicle_parts_dealers - furniture_home_furnishings_stores - electronics_appliance_stores - building_material_garden_equipment_supplies_dealers - food_beverage_stores - health_personal_care_stores - gasoline_stations - clothing_accessories_stores - sporting_goods_hobby_book_music_stores - general_merchandise_stores - miscellaneous_store_retailers - nonstore_retailers - air_transportation - rail_transportation - water_transportation - truck_transportation - transit_ground_passenger_transportation - pipeline_transportation - scenic_sightseeing_transportation - support_activities_transportation - postal_service - couriers_messengers - warehousing_storage - publishing_industries - motion_picture_sound_recording_industries - broadcasting - internet_publishing_broadcasting - telecommunications - data_processing_hosting_related_services - other_information_services - monetary_authorities_central_bank - credit_intermediation_related_activities - securities_commodity_contracts_financial_investments - insurance_carriers_related_activities - funds_trusts_other_financial_vehicles - real_estate - rental_leasing_services - lessors_nonfinancial_intangible_assets - professional_scientific_technical - management_of_companies - administrative_support_services - waste_management_remediation_services - educational_services - ambulatory_health_care_services - hospitals - nursing_residential_care_facilities - social_assistance - performing_arts_spectator_sports - museums_historical_sites - amusement_gambling_recreation_industries - accommodation - food_services_drinking_places - repair_maintenance - personal_laundry_services - religious_grantmaking_civic_professional_organizations - private_households - public_administration description: >- Array of NAICS-subsector slugs (e.g. `telecommunications`, `real_estate`). business_website: type: string description: Business website URL. status: type: string enum: - active - inactive - suspended default: active description: Ignored on create — new users always start as `CREATED`. external_id: type: string description: Your own reference ID for this user (stored as `partnerUserId`). phone: type: string description: >- Phone in E.164 format, e.g. `+14155551234`. Spaces and dashes are sanitized before validation. formation_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Date the entity was formed, `YYYY-MM-DD`. formation_state: type: string description: State or province of formation. formation_country: type: string minLength: 3 maxLength: 3 description: Country of formation as ISO **alpha-3**. registered_address: type: object properties: street_line_1: type: string street_line_2: type: string city: type: string subdivision: type: string postal_code: type: string country: type: string minLength: 3 maxLength: 3 description: Registered (legal) business address. physical_address: type: object properties: street_line_1: type: string street_line_2: type: string city: type: string subdivision: type: string postal_code: type: string country: type: string minLength: 3 maxLength: 3 description: Physical operating address, if different from registered. address_street: type: string maxLength: 70 description: Street address (≤ 70 chars). Flat (V2) address form. address_street_2: type: string maxLength: 70 description: Apartment, suite, or unit (≤ 70 chars). address_city: type: string description: City. address_state: type: string description: State or province (US state for USA users). address_zip_code: type: string description: ZIP or postal code. address_country: type: string description: >- Country as ISO **alpha-3**. With `type`, selects the user category; users in restricted countries are not VA-eligible. representative_first_name: type: string description: Authorized representative — given name. representative_last_name: type: string description: Authorized representative — family name. representative_title: type: string description: Representative job title. representative_date_of_birth: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Representative date of birth, `YYYY-MM-DD`. On update the field is named `representative_birth_date`. representative_ssn: type: string description: Representative SSN (US businesses). ein: type: string description: >- US business tax ID. May also be sent inside `identifying_information` as `{ "type": "ein", "number": "…" }`. cnpj: type: string description: Brazilian business tax ID. rfc: type: string description: Mexican tax ID. document_type: type: string description: >- Primary government document type (e.g. `passport`, `drivers_license`). document_number: type: string description: Primary government document number. document_country: type: string description: Issuing country of the primary document, ISO **alpha-3**. pep_status: type: boolean description: Whether the user is a Politically Exposed Person. tos_accepted_version: type: string description: >- Terms-of-service version the user accepted. Kira stamps `tos_accepted_at` on receipt. expected_monthly_payments: type: string description: >- Free-form string. Prefer `expected_monthly_volume` + `expected_transaction_count` for bucketed values. expected_monthly_volume: type: string enum: - less_than_50000 - 50000_to_100000 - 100000_to_500000 - 500000_to_1000000 - 1000000_to_5000000 - 5000000_to_10000000 - more_than_10000000 description: >- Expected monthly volume bucket. Buckets differ for individuals vs businesses. expected_transaction_count: type: string enum: - less_than_10 - 10_to_25 - 26_to_50 - 51_to_100 - 101_to_500 - more_than_500 description: >- Expected monthly transaction-count bucket. Buckets differ for individuals vs businesses. has_material_intermediary_ownership: type: boolean description: Whether ownership flows through intermediary entities. account_purpose: type: string enum: - 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 description: >- Intended account use. **14** values for individuals, **8** (different) values for businesses. source_of_funds: type: string enum: - 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 description: >- Origin of funds. The accepted enum **differs for individuals vs businesses**. high_risk_industries: type: string enum: - 'Yes' - 'No' description: >- Business-only KYB attestation: whether the business operates in a high-risk industry. is_nbfi_vasp: type: string enum: - 'Yes' - 'No' description: >- Business-only KYB attestation: whether the business is a non-bank financial institution or virtual-asset service provider. business_legal_history: type: string enum: - 'Yes' - 'No' description: >- Business-only KYB attestation: whether the business has relevant legal history. transaction_countries: type: array items: type: string minItems: 1 description: >- Business-only. The countries this business expects to transact with, as ISO 3166-1 codes. Some virtual-account onboarding routes require it; when it is absent the requirement is reported in `missing_fields` rather than inferred, so a business that never declared its markets is not recorded as trading anywhere. corporation_taxed_as: type: string description: How a corporation is taxed (ACT route). llc_taxed_as: type: string description: How an LLC is taxed (ACT route). international_entity_type: type: string description: >- Free-text legal entity type for non-US businesses (e.g. `Sociedad de Responsabilidad Limitada`). additional_info: type: object properties: has_us_bank_account: type: string enum: - 'Yes' - 'No' has_denied_bank_account: type: string enum: - 'Yes' - 'No' additionalProperties: type: string description: >- 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). identifying_information: type: array items: type: object properties: type: type: string enum: - national_id - drivers_license - matriculate_id - military_id - permanent_residency_id - state_or_provincial_id - visa - passport - ssn - itin - ein - curp - rfc - cpf - cnpj - tin - nuip - nit - tax_id - proof_of_address - business_formation - source_of_wealth - ein_letter - bylaws - corporate_resolution - certificate_of_registration - certificate_of_good_standing - board_minutes - portfolio_statement description: >- Kind of identity document, tax identifier, or business document. Same value set and advisory-gap behavior as the individual-branch `identifying_information[].type` (see that field), plus business-file types only valid here (attach a file in `documents[]`): `ein_letter`, `bylaws`, `corporate_resolution`, `certificate_of_registration`, `certificate_of_good_standing`, `board_minutes`, `portfolio_statement`. Full value list: government photo IDs (`passport`, `national_id`, `drivers_license`, `matriculate_id`, `military_id`, `permanent_residency_id`, `state_or_provincial_id`, `visa`); tax/identity numbers sent in `number` (`ssn`, `itin`, `ein`, `curp`, `rfc`, `cpf`, `cnpj`, `tin`, `nuip`, `nit`, `tax_id`); and file-attached documents (`proof_of_address`, `business_formation`, `source_of_wealth`, plus the business-file types above). issuing_country: type: string minLength: 3 maxLength: 3 description: Issuing country, ISO **alpha-3**. Required. number: type: string description: Identifier number (for tax IDs or document numbers). description: type: string expiration: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Expiry date, `YYYY-MM-DD`. image_front: type: string format: uri description: >- Legacy way to attach a front/back ID image, kept for backwards compatibility. Takes a document image as an `https://` URL (or a base64 data URI). **Prefer `documents: [{ type: "front" | "back", file }]`** for new integrations — the same value forms and async-URL handling apply there. image_back: type: string format: uri description: >- Legacy way to attach a front/back ID image, kept for backwards compatibility. Takes a document image as an `https://` URL (or a base64 data URI). **Prefer `documents: [{ type: "front" | "back", file }]`** for new integrations — the same value forms and async-URL handling apply there. documents: type: array items: type: object properties: type: type: string enum: - front - back - selfie - file_proof_of_address - file_business_formation - file_source_of_wealth - file_ein_letter - file_bylaws - file_corporate_resolution - file_certificate_of_registration - file_certificate_of_good_standing - file_board_minutes - file_portfolio_statement - file_fatca - file_company_fiscal_registration description: >- Role of this file within the parent identifying-information entry. Government-ID entries must include **both** `front` and `back` — single-sided types (`passport`, `visa`) may send only `front`. `selfie` is a face-match photo: send it in `documents[]` alongside the ID and Kira submits both to the identity provider, which matches the selfie against the ID portrait; on a pass the resulting biometric verification report is attached to the user automatically, with no interactive session required. (For a higher-assurance check that also proves liveness, use `POST /v1/users/{user_id}/liveness-link` instead.) The `file_*` roles each carry the matching supporting document (`file_proof_of_address` a proof of residence — for individuals and business owners alike — plus formation docs, EIN letter, bylaws, corporate resolution, certificate of registration / good standing, board minutes, portfolio statement). `file_fatca` carries the signed tax self-certification (W-9 or W-8BEN) — Kira does not generate this for you, because the form's federal tax classification cannot be derived from the data you send us — and `file_company_fiscal_registration` the tax-registration certificate. Which of these a given user needs depends on the product: read `missing_fields` for the product you are opening rather than uploading the whole set. file: type: string description: >- Document content. **Two forms are accepted:** - **Base64-encoded file** — a data URI of the form `data:;base64,`. Supported MIME types: `image/jpeg`, `image/png`, `application/pdf`. The bytes are uploaded to storage synchronously while the request runs. - **HTTPS URL** — a link to a hosted file (`https://…`; plain `http://` is rejected on every version). Accepted only on API version `2026-04-14` or later. Kira fetches the file **asynchronously**: the host must be on the client's allowed-domains list (defaults to `aiprise.com` / `api.aiprise.com` when none is configured) and the file is re-checked (MIME type + a 30 MB per-file size cap) before it is stored. While the fetch is in flight the stored document carries `download_status: "pending"`; a permanent failure emits a `user.document.download.failed` webhook and is reported in the response `warnings[]` — it never fails the create/update call. **Request-body cap (10 MB):** the whole request is limited to 10 MB and inline base64 counts against it (≈ +33% overhead). For large files prefer the `https://` URL form: it is fetched asynchronously, does NOT count toward the body limit, and accepts files up to 30 MB each. pattern: >- ^(data:(image/jpeg|image/png|application/pdf);base64,.+|https://.+)$ examples: - data:image/jpeg;base64,/9j/4AAQSkZJRg... - >- https://api.aiprise.com/documents/passport-front.jpg description: type: string required: - type - file description: Document images or files for this entry. required: - type - issuing_country description: >- Tax IDs and government documents. Each entry requires `type` and `issuing_country`. documents: type: array items: type: object properties: type: type: string minLength: 1 description: >- Document role/type. Free-form on this legacy array (e.g. `front`, `file_proof_of_address`). Prefer `identifying_information[].documents[]`, which validates the role against a fixed set. file: type: string description: >- Document content. **Two forms are accepted:** - **Base64-encoded file** — a data URI of the form `data:;base64,`. Supported MIME types: `image/jpeg`, `image/png`, `application/pdf`. The bytes are uploaded to storage synchronously while the request runs. - **HTTPS URL** — a link to a hosted file (`https://…`; plain `http://` is rejected on every version). Accepted only on API version `2026-04-14` or later. Kira fetches the file **asynchronously**: the host must be on the client's allowed-domains list (defaults to `aiprise.com` / `api.aiprise.com` when none is configured) and the file is re-checked (MIME type + a 30 MB per-file size cap) before it is stored. While the fetch is in flight the stored document carries `download_status: "pending"`; a permanent failure emits a `user.document.download.failed` webhook and is reported in the response `warnings[]` — it never fails the create/update call. **Request-body cap (10 MB):** the whole request is limited to 10 MB and inline base64 counts against it (≈ +33% overhead). For large files prefer the `https://` URL form: it is fetched asynchronously, does NOT count toward the body limit, and accepts files up to 30 MB each. pattern: >- ^(data:(image/jpeg|image/png|application/pdf);base64,.+|https://.+)$ examples: - data:image/jpeg;base64,/9j/4AAQSkZJRg... - https://api.aiprise.com/documents/passport-front.jpg file_name: type: string description: type: string required: - type - file description: >- Legacy flat document array. Prefer `identifying_information[].documents[]`. associated_persons: type: array items: type: object properties: first_name: type: string middle_name: type: string last_name: type: string email: type: string format: email birth_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ residential_address: type: object properties: street_line_1: type: string street_line_2: type: string city: type: string subdivision: type: string postal_code: type: string country: type: string minLength: 3 maxLength: 3 has_ownership: type: boolean description: >- Whether this person is a beneficial owner. A UBO is recognized by has_ownership: true, NOT by role — set it on every associated person (true for owners, false otherwise). If omitted, the person is not recognized as an owner and 'associated_persons:has_ownership' is reported in the user's missing_fields (advisory — it does not block verification or VA creation). ownership_percentage: type: number minimum: 0 maximum: 100 description: >- The person's ownership stake (0-100). It does not by itself designate a beneficial owner — pair it with has_ownership: true. A business (KYB) must have at least one associated person with has_ownership: true AND ownership_percentage >= 5, or 'associated_persons:beneficial_owner' is reported in the user's missing_fields and verification does not trigger (blocking for a new business; already-verified businesses are grandfathered — surfaced advisory-only, never re-blocked). has_control: type: boolean description: >- Whether this associated person exercises management control over the business (e.g. an officer or director), independent of equity. Distinct from `has_ownership` (equity stake, see `ownership_percentage`) and `is_signer` (authorized signer). Boolean; a person can be any combination of the three (all three accepted `true` together on one person). is_signer: type: boolean description: >- Whether this associated person is an authorized signer for the business (can sign/act on its accounts), independent of equity ownership (`has_ownership`) and management control (`has_control`). Boolean. nationality: type: string country_of_birth: type: string description: >- Country of birth of the associated person (ISO 3166-1 alpha-3). Must not be blank when supplied. occupation: type: string description: >- Occupation of the associated person. Required by some sponsor banks to activate the person; must not be blank when supplied. pep_status: type: boolean description: >- Whether this person is, or has been, a politically exposed person (PEP). Required by some sponsor banks, which ask it of every beneficial owner and signer and refuse the person without an answer. Send it for each associated person: Kira does not answer it on your behalf, and `false` is a real answer — omitting the field is not the same as declaring `false`. gender: type: string enum: - male - female - other description: >- Gender of the associated person. Required by some sponsor banks to verify the person. phone_number: type: string description: >- Phone number of the associated person in E.164 format. Required by some sponsor banks to verify the person. title: type: string ssn: type: string tax_id: type: string document_type: type: string document_number: type: string document_country: type: string metadata: type: object additionalProperties: {} additional_info: type: object additionalProperties: {} address_street: type: string maxLength: 70 address_city: type: string address_state: type: string address_zip_code: type: string address_country: type: string identifying_information: type: array items: type: object properties: type: type: string enum: - national_id - drivers_license - matriculate_id - military_id - permanent_residency_id - state_or_provincial_id - visa - passport - ssn - itin - ein - curp - rfc - cpf - cnpj - tin - nuip - nit - proof_of_address - business_formation - source_of_wealth - ein_letter - bylaws - corporate_resolution - certificate_of_registration - certificate_of_good_standing - board_minutes - portfolio_statement description: >- Kind of identity document, tax identifier, or business document. Same value set and advisory-gap behavior as the individual-branch `identifying_information[].type` (see that field), EXCEPT `tax_id` is not valid for associated persons (sending it returns a 400 here). Plus business-file types only valid here (attach a file in `documents[]`): `ein_letter`, `bylaws`, `corporate_resolution`, `certificate_of_registration`, `certificate_of_good_standing`, `board_minutes`, `portfolio_statement`. Full value list: government photo IDs (`passport`, `national_id`, `drivers_license`, `matriculate_id`, `military_id`, `permanent_residency_id`, `state_or_provincial_id`, `visa`); tax/identity numbers sent in `number` (`ssn`, `itin`, `ein`, `curp`, `rfc`, `cpf`, `cnpj`, `tin`, `nuip`, `nit`); and file-attached documents (`proof_of_address`, `business_formation`, `source_of_wealth`, plus the business-file types above). issuing_country: type: string minLength: 3 maxLength: 3 number: type: string description: type: string expiration: type: string pattern: ^\d{4}-\d{2}-\d{2}$ image_front: type: string description: >- Legacy way to attach a front/back ID image, kept for backwards compatibility. Takes a document image as an `https://` URL (or a base64 data URI). **Prefer `documents: [{ type: "front" | "back", file }]`** for new integrations — the same value forms and async-URL handling apply there. image_back: type: string description: >- Legacy way to attach a front/back ID image, kept for backwards compatibility. Takes a document image as an `https://` URL (or a base64 data URI). **Prefer `documents: [{ type: "front" | "back", file }]`** for new integrations — the same value forms and async-URL handling apply there. documents: type: array items: type: object properties: type: type: string enum: - front - back - selfie - file_proof_of_address - file_business_formation - file_source_of_wealth - file_ein_letter - file_bylaws - file_corporate_resolution - file_certificate_of_registration - file_certificate_of_good_standing - file_board_minutes - file_portfolio_statement - file_fatca - file_company_fiscal_registration description: >- Role of this file within the parent identifying-information entry. Government-ID entries must include **both** `front` and `back` — single-sided types (`passport`, `visa`) may send only `front`. `selfie` is a face-match photo: send it in `documents[]` alongside the ID and Kira submits both to the identity provider, which matches the selfie against the ID portrait; on a pass the resulting biometric verification report is attached to the user automatically, with no interactive session required. (For a higher-assurance check that also proves liveness, use `POST /v1/users/{user_id}/liveness-link` instead.) The `file_*` roles each carry the matching supporting document (`file_proof_of_address` a proof of residence — for individuals and business owners alike — plus formation docs, EIN letter, bylaws, corporate resolution, certificate of registration / good standing, board minutes, portfolio statement). `file_fatca` carries the signed tax self-certification (W-9 or W-8BEN) — Kira does not generate this for you, because the form's federal tax classification cannot be derived from the data you send us — and `file_company_fiscal_registration` the tax-registration certificate. Which of these a given user needs depends on the product: read `missing_fields` for the product you are opening rather than uploading the whole set. file: type: string description: >- Document content. **Two forms are accepted:** - **Base64-encoded file** — a data URI of the form `data:;base64,`. Supported MIME types: `image/jpeg`, `image/png`, `application/pdf`. The bytes are uploaded to storage synchronously while the request runs. - **HTTPS URL** — a link to a hosted file (`https://…`; plain `http://` is rejected on every version). Accepted only on API version `2026-04-14` or later. Kira fetches the file **asynchronously**: the host must be on the client's allowed-domains list (defaults to `aiprise.com` / `api.aiprise.com` when none is configured) and the file is re-checked (MIME type + a 30 MB per-file size cap) before it is stored. While the fetch is in flight the stored document carries `download_status: "pending"`; a permanent failure emits a `user.document.download.failed` webhook and is reported in the response `warnings[]` — it never fails the create/update call. **Request-body cap (10 MB):** the whole request is limited to 10 MB and inline base64 counts against it (≈ +33% overhead). For large files prefer the `https://` URL form: it is fetched asynchronously, does NOT count toward the body limit, and accepts files up to 30 MB each. pattern: >- ^(data:(image/jpeg|image/png|application/pdf);base64,.+|https://.+)$ examples: - data:image/jpeg;base64,/9j/4AAQSkZJRg... - >- https://api.aiprise.com/documents/passport-front.jpg description: type: string required: - type - file required: - type - issuing_country description: UBOs and authorized signers (businesses). Merged by `email`. metadata: type: object additionalProperties: type: string maxLength: 500 description: >- 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. kyc_id: type: string description: Optional partner-supplied KYC session ID. required: - type - business_legal_name - email CreateUserResponse: allOf: - $ref: '#/components/schemas/UserResponse' description: The created user plus create-time verification details. properties: verification_triggered: type: boolean description: Whether a KYC/KYB verification job was enqueued on create. warnings: type: array items: type: string description: >- Non-fatal issues (e.g. a document that failed to upload). Present only when non-empty. ValidationErrorResponse: type: object description: >- Validation / request error. The body shape is **not uniform** across the API — it varies by endpoint and by which validation layer rejects the request. The fields below are the union of what may appear; treat them all as optional. Observed shapes include `{ code, message }`, `{ code, message, errors[] }`, `{ code, error, details[] }`, `{ error, details[] }`, and a nested `{ error: { code, message, details } }`. Always branch on the HTTP status, not on a fixed body shape. properties: code: type: string message: type: string error: type: - string - object description: >- A short error label (e.g. `"Invalid data"`), or on some endpoints a nested `{ code, message, details }` object. errors: type: array items: type: object properties: field: type: string message: type: string required: - field - message details: type: - array - object description: >- Per-issue detail. Shape varies by endpoint — typically an array of `{ message }` or `{ path, message, code }`, occasionally an object. ErrorResponse: type: object properties: message: type: string code: type: string statusCode: type: number error: type: string timestamp: type: string path: type: string details: {} required: - message UserResponse: type: object properties: id: type: string format: uuid description: User UUID. type: type: string enum: - individual - business description: '`individual` or `business`.' email: type: string format: email description: Email address. status: type: string description: >- Lifecycle status: `CREATED`, `VERIFYING`, `REVIEW`, `VERIFIED`, or `REJECTED`. Gate product readiness on this, not on `verification_status`. verification_status: type: string enum: - unverified - started - in_review - verified - rejected - needs_action default: unverified description: >- KYC/KYB status: `unverified`, `started`, `in_review`, `verified`, `rejected`, or `needs_action`. verification_mode: type: string description: '`automatic` or `verification_link`.' verification_link: type: string description: Hosted KYC URL — present only in `verification_link` mode. verification_link_error: type: string description: >- Populated if hosted-link generation failed, or on PUT /v1/users/{user_id} when a bank-migration triggered by the request was deferred or failed. Freeform, human-readable text — branch on verification_link_error_severity, not this string. verification_link_error_severity: type: string enum: - deferred - failed description: >- Machine-readable companion to verification_link_error, present only alongside it on the PUT /v1/users/{user_id} response. `deferred` means nothing is wrong — the triggered bank migration is waiting on something expected or was correctly skipped by a business rule. `failed` means the migration hit a genuine problem. created_at: type: string format: date-time description: Creation timestamp (ISO 8601). updated_at: type: string format: date-time description: Last-update timestamp (ISO 8601). metadata: type: object additionalProperties: {} description: >- Your key-value pairs, plus any client-level default metadata configured for your account (merged at create time; your request keys win on conflict). first_name: type: string description: Given name (individual users). last_name: type: string description: Family name (individual users). middle_name: type: string description: Middle name (individual users), when provided. phone: type: string description: Contact phone in E.164 form (e.g. `+525512345678`). birth_date: type: string description: Date of birth, `YYYY-MM-DD` (individual users). nationality: type: string description: >- Nationality as an ISO **alpha-3** country code (e.g. `MEX`, `USA`). Users use alpha-3; recipients use alpha-2 — map accordingly. gender: type: string enum: - male - female - other description: '`male`, `female`, or `other`, when provided.' residential_address: type: object description: >- The individual's address. **The response renests and renames the flat create-request fields:** `address_street` → `street_line_1`, `address_state` → `subdivision`, `address_zip_code` → `postal_code`, `address_city` → `city`, `address_country` → `country`. Parse this nested shape — the flat `address_*` request fields do not round-trip. properties: street_line_1: type: string street_line_2: type: string city: type: string subdivision: type: string postal_code: type: string country: type: string description: >- Country as an ISO 3166-1 alpha-3 code (e.g. `USA`), returned as stored from the alpha-3 value sent on create/update. formation_country: type: string business_legal_name: type: string company_name: type: string business_type: type: string business_trade_name: type: string business_description: type: string business_industry: type: array items: type: string registered_address: type: object properties: street_line_1: type: string street_line_2: type: string city: type: string subdivision: type: string postal_code: type: string country: type: string physical_address: type: object properties: street_line_1: type: string street_line_2: type: string city: type: string subdivision: type: string postal_code: type: string country: type: string has_material_intermediary_ownership: type: boolean account_purpose: type: string description: >- Write-only in practice: accepted on create/update but currently NOT returned by GET — do not depend on reading it back. source_of_funds: type: string description: >- Write-only in practice: accepted on create/update but currently NOT returned by GET — do not depend on reading it back. eligible_products: type: array description: >- Per-product eligibility, computed from the user's supplied fields against the product matrix — present on the create response and on the single-resource GET (`GET /v1/users/{user_id}`), even before verification. On the list (`GET /v1/users`), present only when the request passed `include_eligibility=true`; omitted otherwise. Each product carries `eligible` (false until the user reaches the product's minimum status, e.g. VERIFIED) and its own `missing_fields`. Verification flips `eligible` to true and clears `missing_fields`; it does not populate the array. A product that is `eligible: false` for a reason no field can clear carries `unsupported_reason` instead of `missing_fields` — verification will not flip it. items: type: object properties: product_id: type: string description: Product UUID. product_code: type: string description: >- Product code, e.g. `usa-virtual-accounts`, `usa-virtual-accounts-act`. product_name: type: string description: Human-readable product name. eligible: type: boolean description: Whether the user can open this product now. missing_fields: type: array items: type: string description: Field tokens still required for this product. unsupported_reason: type: string enum: - enhanced_due_diligence_required description: >- Present only when `eligible` is `false` for a reason no field can clear — a capability not offered for this user yet, rather than an incomplete profile. Mutually exclusive with `missing_fields`: check this first, because supplying fields will not change the verdict. `enhanced_due_diligence_required` — the business's industry requires enhanced due diligence (EDD), which is not supported yet; `POST /v1/virtual-accounts` returns `422` with the same explanation. Branch on this value, not on the message text. missing_fields: type: object description: >- Map of `product_code` → outstanding field tokens, plus a `general` key with the deduplicated union across products. It is populated before verification too; the sole exception is that this top-level aggregate is omitted on the create response for `verification_link`-mode users or when there are zero gaps. additionalProperties: type: array items: type: string capabilities: type: object description: >- Per-subclient bank intent — which banks this subclient has declared it needs. Always present on `GET /v1/users/{id}`, including `{ "requested_banks": [] }` when nothing is declared — never omitted there. On the list (`GET /v1/users`), present only when the request passed `include_eligibility=true`; omitted otherwise. properties: requested_banks: type: array items: type: string description: >- Banks this subclient has expressed intent to use, e.g. `portage`, `slovak_savings_bank`, `austin_capital_trust`. This records intent only — it does not by itself authorize the subclient for a bank your account isn't already authorized for. required: - requested_banks required: - id - type - email - status - created_at - updated_at securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Access token from `POST /auth` (the `data.access_token` value). apiKeyAuth: type: apiKey in: header name: x-api-key description: API key issued by Kira. Required on every request, including `/auth`. ````