> ## 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 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 receive `user.*` webhooks (see [Webhooks](/webhooks/overview)). - `verification_link` — Kira drops every other field you sent and answers with a hosted form for someone to fill in. ## 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: Recipients - name: Quotations - name: Payouts - name: Reference paths: /v1/users: post: tags: - Users summary: Create a user description: > 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 receive `user.*` webhooks (see [Webhooks](/webhooks/overview)). - `verification_link` — Kira drops every other field you sent and answers with a hosted form for someone to fill in. operationId: post_v1-users parameters: - in: header name: X-Api-Version required: false description: >- Version applied to this request. It wins over your account's pinned version — see [Versioning](/using-the-api/versioning). schema: type: string example: '2026-04-14' - in: header name: Idempotency-Key required: true schema: type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 description: >- 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`. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest' examples: 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 responses: '201': description: >- The business was created. Verification has not necessarily started — read `verification_triggered` and `missing_fields`. content: application/json: schema: type: object properties: id: type: string description: >- The id of the business you just created. Use it on every other call. type: type: string description: Always `business`. email: type: string status: type: string description: >- Starts at `CREATED`. See [User values](/reference/users/values#status). verification_status: type: string description: >- Starts at `unverified`. See [User values](/reference/users/values#verification_status). created_at: type: string description: ISO 8601. updated_at: type: string description: ISO 8601. verification_mode: type: string description: The mode this business was created with. verification_link: type: string description: >- 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. metadata: type: object description: The key-value pairs you sent. formation_country: type: string description: ISO **alpha-3**. business_legal_name: type: string registered_address: $ref: '#/components/schemas/Address' verification_triggered: type: boolean description: >- Whether verification started. It is `false` while any product still reports missing fields. eligible_products: type: array description: >- What the business can use, product by product. Every entry is `eligible: false` until verification passes. items: type: object properties: product_id: type: string product_code: type: string description: >- The code to match on. The set depends on what your account is authorized for. product_name: type: string eligible: type: boolean missing_fields: type: array description: Field tokens still needed for this product. items: type: string missing_fields: type: object description: >- 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. additionalProperties: type: array items: type: string identifying_information: type: - array - 'null' description: The records you sent, with the stored files. items: type: object properties: type: type: string description: What the record is. number: type: string description: >- The document or registration number, when it has one. issuing_country: type: string description: Country that issued it, ISO **alpha-3**. documents: type: array description: The files stored for this record. items: type: object properties: type: type: string description: What the file shows. file: type: string description: >- A short-lived download URL for the file you just uploaded. It expires in minutes and is only returned here — the read endpoints leave it out. file_name: type: string description: The stored file name. uploaded_at: type: string description: When the file was stored, ISO 8601. content_type: type: string description: The file's MIME type. associated_persons: type: - array - 'null' description: >- The people you sent. Fields Kira does not keep are dropped from the echo. items: $ref: '#/components/schemas/AssociatedPerson' warnings: type: array description: >- Non-fatal problems with the documents you sent. Absent when there are none. items: type: string example: id: e687484f-74ef-43a8-a68a-5bf78aa2e721 type: business email: ops@example.com status: CREATED verification_status: unverified created_at: '2026-09-01T12:00:00.000Z' updated_at: '2026-09-01T12:00:00.000Z' verification_mode: automatic metadata: {} formation_country: USA business_legal_name: Northwind Trading LLC registered_address: street_line_1: 1 Market Street street_line_2: '' city: San Francisco subdivision: CA postal_code: '94105' country: USA verification_triggered: false eligible_products: - product_id: usa-virtual-accounts product_code: usa-virtual-accounts product_name: USA Virtual Accounts eligible: false missing_fields: - identifying_information:file_portfolio_statement - identifying_information:file_board_minutes missing_fields: usa-virtual-accounts: - identifying_information:file_portfolio_statement - identifying_information:file_board_minutes general: - identifying_information:file_portfolio_statement - identifying_information:file_board_minutes identifying_information: - type: business_formation issuing_country: USA documents: - type: file_business_formation file: https://… file_name: >- 1712345678901-a1b2c3d4-business_formation-file_business_formation.pdf uploaded_at: '2026-09-01T12:00:01.000Z' content_type: application/pdf associated_persons: - first_name: Alice last_name: Smith email: alice@example.com birth_date: '1980-05-15' nationality: USA document_type: passport document_number: X1234567 document_country: USA has_ownership: true ownership_percentage: 100 identifying_information: - type: ssn number: 000-00-0000 issuing_country: USA '400': description: >- The request was refused and nothing was created. Two different bodies come back: - **A rule you hit.** `code` names it and `message` explains it — for example `business_only` when `type` is `individual`. - **A field that did not validate.** `error` reads `Invalid request data` and `details` lists one entry per problem, each with the field's `path`, a `message`, and its own `code` (`invalid_enum_value`, `invalid_type`, and so on). content: application/json: schema: type: object properties: error: type: string description: >- `Bad Request` on a rule, `Invalid request data` on a field problem. code: type: string description: The rule you hit. Only on the first kind. message: type: string description: What is wrong, in words. Only on the first kind. statusCode: type: integer description: Always `400`. Only on the first kind. timestamp: type: string description: ISO 8601. Only on the first kind. details: type: array description: One entry per field problem. Only on the second kind. items: type: object properties: path: type: string description: The field that did not validate. message: type: string description: >- What is wrong with it. On an enum it lists every accepted value. code: type: string description: >- The kind of problem — `invalid_enum_value`, `invalid_type`. examples: business-only: summary: type was individual value: statusCode: 400 error: Bad Request message: >- New individual sub-clients are no longer accepted; a sub-client must be a business. timestamp: '2026-09-07T15:22:56.746Z' code: business_only invalid-enum: summary: A field carried a value outside its set value: error: Invalid request data details: - path: account_purpose message: >- Invalid enum value. Expected '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', received 'no_such_purpose' code: invalid_enum_value missing-field: summary: A required field is missing value: error: Invalid request data details: - path: email message: Required code: invalid_type '401': description: >- Your credentials were not accepted. The message talks about routing, but it is the same body for every cause, so it is not a guide to which one: - The `Authorization` header is missing, expired or wrong. Get a new token from [Get access token](/api-reference/authentication/get-access-token). - The `x-api-key` header is missing or wrong. - One is present and the other is not. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: invalid_request message: >- The request could not be matched to a valid route, or was malformed. Verify the path and HTTP method against the API reference. This is a routing or request error, not a credentials or signature problem. '409': description: >- You reused an `Idempotency-Key` with a different body. Nothing was created. Send a fresh key for a new business, or repeat the exact body to get the original result back. This body carries a single `detail` field — it does not follow the shape of the other errors. content: application/json: schema: type: object properties: detail: type: string description: What went wrong, in words. example: detail: >- Idempotency key has already been used with different request data security: - bearerAuth: [] apiKeyAuth: [] servers: - url: https://api.balampay.com/sandbox description: Sandbox - url: https://api.balampay.com description: Production components: schemas: CreateUserRequest: oneOf: - type: object properties: type: type: string enum: - business description: >- Must be `business`. Individuals created before this endpoint stopped accepting them keep working, and still read as `type: individual`. verification_mode: type: string enum: - automatic - verification_link description: >- How this business gets verified. See [User values](/reference/users/values#verification_mode) for what each value means. capabilities: type: object description: >- 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. properties: requested_banks: type: array items: type: string enum: - austin_capital_trust - jp_morgan description: >- Which banks this business plans to use. See [Virtual account values](/reference/virtual-accounts/values#bank) for the accepted values and which environment each one works in. Naming a bank here puts the business on that bank's verification level, so it is what triggers any extra KYB that bank asks for. It records intent only — it does not authorize your account for a bank it is not already authorized for. 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: >- The locale for the hosted verification form. It only matters when `verification_mode` is `verification_link`. See [User values](/reference/users/values#language) for the accepted values. business_legal_name: type: string minLength: 1 description: The registered legal name of the business. email: type: string format: email description: The business's email address. business_type: type: string description: >- The legal structure of the business. See [User values](/reference/users/values#business_type) for the accepted values. Accepted here, but not returned in the user object — do not expect to read it back. business_trade_name: type: string description: >- Trade name, if different from the legal name. Accepted here, but not returned in the user object — do not expect to read it back. doing_business_as: type: string description: >- The name the business trades under, when it is different from its legal name. Accepted here, but not returned in the user object — do not expect to read it back. business_description: type: string description: >- Short description of what the business does. Accepted here, but not returned in the user object — do not expect to read it back. business_industry: type: array items: type: string description: >- The industries the business works in, as NAICS subsector slugs — `telecommunications`, `real_estate`, `construction_of_buildings`. See [User values](/reference/users/values#business_industry) for the full list. Accepted here, but not returned in the user object — do not expect to read it back. business_website: type: string description: Business website URL. status: type: string 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. Accepted here, but not returned in the user object — do not expect to read it back. 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: >- How much the business expects to move in a month. See [User values](/reference/users/values#expected_monthly_volume) for the buckets. 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: >- How many payments the business expects to make in a month. See [User values](/reference/users/values#expected_transaction_count) for the buckets. has_material_intermediary_ownership: type: boolean description: >- Whether ownership flows through intermediary entities. Accepted here, but not returned in the user object — do not expect to read it back. 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: >- What the business will use the account for. See [User values](/reference/users/values#account_purpose) for the accepted values. Accepted here, but not returned in the user object — do not expect to read it back. 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: >- Where the money the business moves comes from. See [User values](/reference/users/values#source_of_funds) for the accepted values. Accepted here, but not returned in the user object — do not expect to read it back. high_risk_industries: type: string enum: - 'Yes' - 'No' description: >- A KYB attestation: whether the business operates in a high-risk industry. is_nbfi_vasp: type: string enum: - 'Yes' - 'No' description: >- A 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: >- A KYB attestation: whether the business has relevant legal history. transaction_countries: type: array items: type: string minItems: 1 description: >- 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. 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 description: >- What kind of record this is — `passport`, `ein`, `business_formation`. The kind decides where its value goes: an identifier in `number`, a file in `documents[]`. See [User values](/reference/users/values#identifying_information-types) for the full list. 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: >- An older way to attach an ID image, kept working for integrations that already use it. Takes the same value forms as `file`. For anything new use `documents: [{ type: "front" | "back", file }]` instead. image_back: type: string format: uri description: >- An older way to attach an ID image, kept working for integrations that already use it. Takes the same value forms as `file`. For anything new use `documents: [{ type: "front" | "back", file }]` instead. documents: type: array items: type: object properties: type: type: string description: >- What this file is within its record — `front`, `back`, `selfie`, or one of the `file_*` supporting documents. See [User values](/reference/users/values#documents-types) for the full list and what each one carries. file: type: string description: >- The file itself, in one of two forms. - **Base64** — `data:;base64,`, for `image/jpeg`, `image/png` or `application/pdf`. It is stored while the request runs. - **HTTPS URL** — a link Kira fetches afterwards. `http://` is refused, and the host must be on your allowed-domains list. **Prefer the URL for anything large.** The whole request body is capped at 10 MB and base64 adds about a third to what you send; a fetched file does not count against that cap and can be up to 30 MB. While a URL is being fetched the stored document reads `download_status: "pending"`. A permanent failure emits a `user.document.download.failed` webhook (see [Webhooks](/webhooks/overview)) and shows up in the response's `warnings[]` — it never fails the call. 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: >- The file itself, in one of two forms. - **Base64** — `data:;base64,`, for `image/jpeg`, `image/png` or `application/pdf`. It is stored while the request runs. - **HTTPS URL** — a link Kira fetches afterwards. `http://` is refused, and the host must be on your allowed-domains list. **Prefer the URL for anything large.** The whole request body is capped at 10 MB and base64 adds about a third to what you send; a fetched file does not count against that cap and can be up to 30 MB. While a URL is being fetched the stored document reads `download_status: "pending"`. A permanent failure emits a `user.document.download.failed` webhook (see [Webhooks](/webhooks/overview)) and shows up in the response's `warnings[]` — it never fails the call. 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 owns part of the business. Send it on every person, `true` or `false`. Leaving it out is not the same as `false`: the person is not counted as an owner and `associated_persons:has_ownership` shows up in `missing_fields`. ownership_percentage: type: number minimum: 0 maximum: 100 description: >- How much of the business this person owns, from 0 to 100. On its own it does not make them an owner — set `has_ownership` too. has_control: type: boolean description: >- Whether this person controls the business — an officer or a director, whether or not they own any of it. is_signer: type: boolean description: >- Whether this person can sign for the business and act on its accounts. 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. Send it for every person. Some banks ask it of every owner and signer and refuse a person with no answer. `false` is a real answer — leaving the field out is not the same thing. 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 description: >- What kind of record this is — `passport`, `ein`, `business_formation`. The kind decides where its value goes: an identifier in `number`, a file in `documents[]`. See [User values](/reference/users/values#identifying_information-types) for the full list. 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: >- An older way to attach an ID image, kept working for integrations that already use it. Takes the same value forms as `file`. For anything new use `documents: [{ type: "front" | "back", file }]` instead. image_back: type: string description: >- An older way to attach an ID image, kept working for integrations that already use it. Takes the same value forms as `file`. For anything new use `documents: [{ type: "front" | "back", file }]` instead. documents: type: array items: type: object properties: type: type: string description: >- What this file is within its record — `front`, `back`, `selfie`, or one of the `file_*` supporting documents. See [User values](/reference/users/values#documents-types) for the full list and what each one carries. file: type: string description: >- The file itself, in one of two forms. - **Base64** — `data:;base64,`, for `image/jpeg`, `image/png` or `application/pdf`. It is stored while the request runs. - **HTTPS URL** — a link Kira fetches afterwards. `http://` is refused, and the host must be on your allowed-domains list. **Prefer the URL for anything large.** The whole request body is capped at 10 MB and base64 adds about a third to what you send; a fetched file does not count against that cap and can be up to 30 MB. While a URL is being fetched the stored document reads `download_status: "pending"`. A permanent failure emits a `user.document.download.failed` webhook (see [Webhooks](/webhooks/overview)) and shows up in the response's `warnings[]` — it never fails the call. 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: >- The people behind the business — owners, people in control, and authorized signers. Kira matches them by `email`. **A business needs at least one owner holding 5% or more**: one person with `has_ownership: true` and `ownership_percentage` of `5` or higher. 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. The three roles are independent, and one person can hold all of them. 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 Address: type: object description: A postal address. properties: street_line_1: type: string street_line_2: type: string city: type: string subdivision: type: string description: >- The state or province. For users in the USA, the 2-letter state code (`FL`). It comes back exactly as you sent it. postal_code: type: string country: type: string description: >- Country as an ISO **alpha-3** code (`USA`). It comes back exactly as you sent it. AssociatedPerson: type: object description: >- One person tied to a business — an owner, a signer, or someone in control. properties: person_id: type: string description: >- Kira's id for this person, when there is one. Match people by `email` rather than relying on it. first_name: type: string middle_name: type: string last_name: type: string email: type: string birth_date: type: string description: Date of birth, `YYYY-MM-DD`. gender: type: string nationality: type: string description: ISO **alpha-3** country code. country_of_birth: type: string description: ISO **alpha-3** country code. phone_number: type: string description: Phone in E.164 form. occupation: type: string description: Occupation code. title: type: string description: The person's role in the business — `CEO`. pep_status: type: boolean description: Whether the person is, or has been, a politically exposed person. is_signer: type: boolean description: Whether the person can sign for the business. has_control: type: boolean description: Whether the person controls the business. has_ownership: type: boolean description: Whether the person owns part of the business. ownership_percentage: type: number description: How much of the business the person owns, as a percentage. ssn: type: string description: US Social Security number, on US people. document_type: type: string description: The person's primary document — `passport`, `drivers_license`. document_number: type: string document_country: type: string description: ISO **alpha-3** country code. address_street: type: string description: >- Flat address field. Some people carry these instead of `residential_address`. address_city: type: string address_state: type: string address_zip_code: type: string address_country: type: string description: ISO **alpha-3** country code. residential_address: $ref: '#/components/schemas/Address' identifying_information: type: array description: The person's own identity records. items: $ref: '#/components/schemas/IdentifyingInformation' 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 IdentifyingInformation: type: object description: One identity or registration record. properties: type: type: string description: >- What the record is — `passport`, `ssn`, `drivers_license`, `business_formation`, `ein_letter`, `proof_of_address`, `source_of_wealth`. number: type: string description: The document or registration number, when the record has one. expiration: type: string description: Expiry date, `YYYY-MM-DD`, on records that expire. issuing_country: type: string description: Country that issued it, as an ISO **alpha-3** code. documents: type: array description: The files uploaded for this record. items: type: object description: One uploaded file. properties: type: type: string description: >- What the file shows — `front`, `back`, `selfie`, or a `file_*` document type. file_name: type: string description: The stored file name. It is not a download URL. uploaded_at: type: string description: When the file was uploaded, ISO 8601. content_type: type: string description: The file's MIME type — `application/pdf`, `image/jpeg`. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- The `data.access_token` value from [Get access token](/api-reference/authentication/get-access-token). apiKeyAuth: type: apiKey in: header name: x-api-key description: API key issued by Kira. ````