Skip to main content
PUT

Authorizations

Authorization
string
header
required

The data.access_token value from Get access token.

Headers

X-Api-Version
string

Version applied to this request. It wins over your account's pinned version — see Versioning.

Example:

"2026-04-14"

Path Parameters

user_id
string<uuid>
required

The id of the user to change. It must be a UUID.

Body

application/json

address_country, formation_country, document_country, residential_address.country, and the address and document country fields in associated_persons[] take an ISO 3166-1 alpha-3 code.

capabilities
object

Which banks this user plans to use. This records intent only — authorizing an account for a bank is separate.

verification_mode
enum<string>

How the user gets verified.

See User values for the accepted values.

Available options:
automatic,
verification_link
first_name
string

The person's given name.

Minimum string length: 1
middle_name
string

The person's middle name.

last_name
string

The person's family name.

Minimum string length: 1
birth_date
string

Date of birth, YYYY-MM-DD. Must be 18+.

Pattern: ^\d{4}-\d{2}-\d{2}$
nationality
string

ISO alpha-3 nationality.

Required string length: 3
gender
enum<string>

The person's gender.

Available options:
male,
female,
other
immigration_status
string

Exact string, e.g. U.S. Citizen, Permanent U.S. Resident, Non-Resident of U.S.

The registered legal name of the business.

Minimum string length: 1
company_name
string

Backward-compatible alias for business_legal_name.

Accepted here, but not returned in the user object.

Minimum string length: 1
doing_business_as
string

The name the business trades under. Required to verify a business. A business with no trade name sends its legal name.

business_type
string

The legal structure of the business.

See User values for the accepted values.

Accepted here, but not returned in the user object.

business_industry
string[]

The industry the business works in, as a NAICS subsector slug — telecommunications, real_estate, construction_of_buildings.

See User values for the accepted values. Send one industry. A second is refused with a 400.

Accepted here, but not returned in the user object.

Maximum array length: 1
business_description
string

Accepted here, but not returned in the user object.

business_website
string<uri>

The business's website.

formation_date
string

The date the business was formed, YYYY-MM-DD.

Pattern: ^\d{4}-\d{2}-\d{2}$
formation_state
string

The state or province the business was formed in.

formation_country
string

The country the business was formed in, as an ISO alpha-3 code. The bank's verifier records it as the country the business is registered in. The address country never stands in for it.

Required string length: 3
representative_first_name
string

Given name of the person representing the business.

representative_last_name
string

Family name of the person representing the business.

representative_title
string

The representative's role in the business.

representative_birth_date
string

Representative date of birth, YYYY-MM-DD. On create this field is representative_date_of_birth.

Pattern: ^\d{4}-\d{2}-\d{2}$
representative_ssn
string

The representative's US Social Security number.

email
string<email>

The user's email address.

phone
string

E.164 format, e.g. +14155551234.

document_type
string

The person's primary identity document.

document_number
string

The number on that document.

document_country
string

The country that issued it, as an ISO alpha-3 code.

Required string length: 3
address_street
string

Street address.

address_street_2
string

Apartment, suite or unit.

address_city
string

City.

address_state
string

State or province. For the USA, the 2-letter state code.

address_zip_code
string

ZIP or postal code.

address_country
string

ISO alpha-3 country.

Required string length: 3
residential_address
object

Nested residential address (V1). You may instead use the flat address_* fields.

ssn
string

US individuals only — do NOT send for non-US individuals.

cpf
string

Brazil individual tax ID.

curp
string

Mexico individual ID.

rfc
string

Mexico tax ID.

ein
string

US businesses only — do NOT send for non-US businesses.

cnpj
string

Brazil business tax ID.

tax_id
string

Generic international tax ID.

tax_id_type
string

Which kind of tax identifier tax_id carries.

source_of_funds
string

Where the money comes from.

See User values for the accepted values.

Accepted here, but not returned in the user object.

account_purpose
string

What the account will be used for.

See User values for the accepted values.

Accepted here, but not returned in the user object.

expected_monthly_payments
string

How much is expected in payments in a month, as a bucket.

A business takes the business buckets in User values. Any other value for a business is refused with a 400.

expected_monthly_volume
enum<string>

How much is expected to move in a month.

See User values for the accepted values.

Available options:
less_than_10000,
10000_to_49999,
50000_to_199999,
200000_to_999999,
1000000_or_more,
less_than_50000,
50000_to_100000,
100000_to_500000,
500000_to_1000000,
1000000_to_5000000,
5000000_to_10000000,
more_than_10000000
expected_transaction_count
enum<string>

How many payments are expected in a month.

See User values for the accepted values.

Available options:
1_to_10,
11_to_50,
51_to_200,
more_than_200,
less_than_10,
10_to_25,
26_to_50,
51_to_100,
101_to_500,
more_than_500
employment_status
enum<string>

What the person does for a living.

See User values for the accepted values.

Available options:
employed,
self_employed,
unemployed,
retired,
student
occupation
string

The person's occupation, as free text or a code. See User values for the accepted codes.

current_employer
string

Send only when employment_status = employed.

income_source
string

Where the person's income comes from.

pep_status
boolean

Whether this person is, or has been, a politically exposed person.

false is a real answer — leaving the field out is not the same thing.

high_risk_industries
enum<string>

A KYB attestation: whether the business operates in a high-risk industry.

Available options:
Yes,
No
is_nbfi_vasp
enum<string>

A KYB attestation: whether the business is a non-bank financial institution or a virtual-asset service provider.

Available options:
Yes,
No

A KYB attestation: whether the business has relevant legal history.

Available options:
Yes,
No
transaction_countries
string[]

The countries the user expects to transact with, as ISO 3166-1 codes.

When it is absent the gap is reported in missing_fields — Kira never guesses a market you did not declare.

Minimum array length: 1
tos_accepted_version
string

Terms-of-service version the user accepted.

corporation_taxed_as
string

How the corporation is taxed.

llc_taxed_as
string

How the limited liability company is taxed.

international_entity_type
string

Free-text entity type for non-US businesses.

government_document_type
string

The kind of government document being supplied.

additional_info
object

Free-form string map. International users include has_us_bank_account / has_denied_bank_account as Yes or No. The value is case-sensitive, and lowercase is not accepted.

identifying_information
object[]

Tax IDs and government documents to add or replace. Each entry requires type and issuing_country.

associated_persons
object[]

UBOs and authorized signers (businesses). Merged by email. The phone field here is phone_number.

has_ownership, has_control and is_signer are independent. One person can hold any combination of the three.

documents
object[]

Legacy flat document array. Prefer identifying_information[].documents[].

metadata
object

A patch, not a replacement: keys shallow-merge, an empty-string value deletes that key, {} clears all. ≤ 50 keys; key 1–40 chars, no [ or ].

Response

The change was applied. updated_fields says what was written.

The user after the change, plus what the change did.

id
string<uuid>

User UUID.

type
string

Whether the user is a company or a person.

Available options: business, individual.

See User values for what each one means.

email
string<email>

Email address.

status
string

Where the user sits in its lifecycle.

Available options: CREATED, VERIFYING, REVIEW, VERIFIED, REJECTED, plus the legacy ACTIVE, INACTIVE and SUSPENDED.

See User values for what each one means.

verification_status
string

The result of the user's identity or business check.

Available options: unverified, started, in_review, verified, rejected, needs_action.

See User values for what each one means.

created_at
string<date-time>

Creation timestamp (ISO 8601).

updated_at
string<date-time>

Last-update timestamp (ISO 8601).

verification_mode
string

automatic or verification_link.

Hosted KYC URL — present only in verification_link mode.

A plain-text note about something the request could not finish — the hosted verification link, or a move of this user to a different bank.

The wording can change, so branch on verification_link_error_severity, never on this string.

Whether the note in verification_link_error asks anything of you.

See User values for what each value means.

Available options:
deferred,
failed
metadata
object

The key-value pairs you stored on this user.

If your account has default metadata configured, it is merged in when the user is created and your own keys win on a conflict.

first_name
string

Given name (individual users).

last_name
string

Family name (individual users).

middle_name
string

Middle name (individual users), when provided.

phone
string

Contact phone in E.164 form (e.g. +525512345678).

birth_date
string

Date of birth, YYYY-MM-DD (individual users).

nationality
string

The person's nationality, as an ISO alpha-3 country code — USA, MEX.

country_of_birth
string

Where the person was born, as an ISO alpha-3 country code. Absent when it was never set.

gender
string

male, female, or other, when provided.

residential_address
object

The person's address, as a nested object.

formation_country
string

Country the business was formed in, as an ISO alpha-3 code.

The registered legal name of the business.

registered_address
object

The registered, legal address of the business.

requires_reverification
boolean

Whether this change re-triggered the identity check. It turns true when you touch a field the user's category needs for verification.

Users on a hosted form are never re-queued.

verification_triggered
boolean

Whether verification started as a result of this change.

updated_fields
string[]

The fields this call wrote, in the order you sent them. Use it to confirm the API read what you meant.

eligible_products
object[]

What this user can already use, product by product.

Each entry carries eligible, and when that is false, the reason why:

  • missing_fields — data is missing. Send it, and the product turns eligible once the user passes verification.
  • unsupported_reason — nothing you send will change the answer.

A product stays eligible: false until the user reaches the status that product asks for. That status is VERIFIED.

missing_fields
object

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.

identifying_information
object[] | null

The user's identity or registration records. null when none are stored, and absent on users whose verification runs through a hosted link.

associated_persons
object[] | null

The people tied to a business. null for a person, and absent on users whose verification runs through a hosted link.

capabilities
object

The banks the user has declared, after the ones you sent were added to those already on file. Only when the request sent at least one bank in capabilities.requested_banks.

warnings
string[]

Non-fatal problems with the documents you sent. A document that fails to upload shows up here and does not fail the call. Absent when there are none.