Skip to main content
PUT
Update a user
Stable since 2026-04-14 — unchanged in 2026-06-01.

Authorizations

Authorization
string
header
required

Access token from POST /auth (the data.access_token value).

x-api-key
string
header
required

API key issued by Kira. Required on every request, including /auth.

Headers

X-Api-Version
string

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.

Example:

"2026-06-01"

Path Parameters

user_id
string<uuid>
required

User UUID.

Body

application/json

Partial update — every field is optional; only the fields you send are written. Accepts both individual and business fields, with combined enums for source_of_funds / account_purpose / volume / count. Any key not defined by this schema is rejected with 400 — it is never silently dropped.

capabilities
object

Per-subclient bank intent — merged (union) with whatever is already stored. A PUT can only ADD a bank; it never removes a previously-declared one by omission. Optional; omit it to leave the subclient's declared banks unchanged.

verification_mode
enum<string>

automatic (default) leaves the existing verification flow unchanged. verification_link only returns a hosted KYC URL (verification_link) when this request also newly declares a bank that requires moving the subclient's applicant to a stricter level, and that move succeeds — otherwise verification_mode alone has no visible effect on the response.

Available options:
automatic,
verification_link
first_name
string
Minimum string length: 1
middle_name
string
last_name
string
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>
Available options:
male,
female,
other
immigration_status
string

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

Minimum string length: 1
company_name
string

Backward-compatible alias for business_legal_name.

Minimum string length: 1
doing_business_as
string
business_type
enum<string>

Legal structure (deprecated aliases accepted). Note: business_trade_name is NOT updatable via this endpoint.

Available options:
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
business_industry
enum<string>[]

Array of NAICS-subsector slugs.

Available options:
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
business_description
string
business_website
string<uri>
formation_date
string
Pattern: ^\d{4}-\d{2}-\d{2}$
formation_state
string
formation_country
string
Required string length: 3
representative_first_name
string
representative_last_name
string
representative_title
string
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
email
string<email>
phone
string

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

document_type
string
document_number
string
document_country
string
Required string length: 3
address_street
string
address_street_2
string
address_city
string
address_state
string
address_zip_code
string
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

Free-text label for the type of the value in tax_id (e.g. "rfc", "ein"). Unvalidated string, not a fixed enum — confirmed by successfully setting an arbitrary label (accepted and reported in the response's updated_fields). For a validated, typed tax identifier, prefer identifying_information[] instead.

source_of_funds
enum<string>

Combined individual + business enum.

Available options:
salary,
self_employment_income,
investment_proceeds,
savings_inheritance_gift,
business_loans,
inter_company_funds,
owners_capital,
sales_of_goods_and_services,
tax_refund,
third_party_funds,
treasury_reserves,
company_funds,
gifts,
inheritance,
investments_loans,
pension_retirement,
sale_of_assets_real_estate,
savings,
someone_elses_funds
account_purpose
enum<string>

Combined individual + business enum.

Available options:
receive_payments,
manage_professional_income,
make_payments,
manage_personal_funds,
investment_trading,
charitable_donations,
ecommerce_retail_payments,
investment_purposes,
purchase_goods_and_services,
receive_payments_for_goods_and_services,
internal_treasury,
third_party_money_transmission,
receive_salary,
receive_payment_for_freelancing,
operating_a_company,
payments_to_friends_or_family_abroad,
personal_or_living_expenses,
protect_wealth
expected_monthly_payments
string

Free-form. Prefer expected_monthly_volume + expected_transaction_count.

expected_monthly_volume
enum<string>

Combined individual + business buckets.

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>

Combined individual + business buckets.

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>
Available options:
employed,
self_employed,
unemployed,
retired,
student
occupation
string
current_employer
string

Send only when employment_status = employed.

income_source
string

Free-text description of the individual's income source. Unlike source_of_funds (a fixed enum), this field is unvalidated — confirmed by successfully setting a value outside the source_of_funds enum list (accepted and reported in the response's updated_fields).

pep_status
boolean

Whether the user is a Politically Exposed Person (PEP). Boolean — sending a string instead of a boolean is rejected with "Expected boolean, received string".

high_risk_industries
enum<string>

Business-only KYB attestation, Yes or No: does the business operate in a high-risk industry? Same field as CreateUserRequest.high_risk_industries.

Available options:
Yes,
No
is_nbfi_vasp
enum<string>

Business-only KYB attestation, Yes or No: is the business a Non-Bank Financial Institution (NBFI) or Virtual Asset Service Provider (VASP)? Same field as CreateUserRequest.is_nbfi_vasp.

Available options:
Yes,
No

Business-only KYB attestation, Yes or No: has the business ever been involved in legal proceedings? Same field and enum as CreateUserRequest.business_legal_history.

Available options:
Yes,
No
transaction_countries
string[]

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.

Minimum array length: 1
tos_accepted_version
string

Terms-of-service version the user accepted.

corporation_taxed_as
string
llc_taxed_as
string
international_entity_type
string

Free-text entity type for non-US businesses.

government_document_type
string
additional_info
object

Free-form string map. International users include has_us_bank_account / has_denied_bank_account as Yes/No (case-sensitive; lowercase is not accepted by ACT provisioning).

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. Note the phone field here is phone_number.

documents
object[]

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

metadata
object

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

Response

Success.

The updated user plus the update result.

id
string<uuid>
required

User UUID.

type
enum<string>
required

individual or business.

Available options:
individual,
business
email
string<email>
required

Email address.

status
string
required

Lifecycle status: CREATED, VERIFYING, REVIEW, VERIFIED, or REJECTED. Gate product readiness on this, not on verification_status.

created_at
string<date-time>
required

Creation timestamp (ISO 8601).

updated_at
string<date-time>
required

Last-update timestamp (ISO 8601).

verification_status
enum<string>
default:unverified

KYC/KYB status: unverified, started, in_review, verified, rejected, or needs_action.

Available options:
unverified,
started,
in_review,
verified,
rejected,
needs_action
verification_mode
string

automatic or verification_link.

Hosted KYC URL — present only in verification_link mode.

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.

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.

Available options:
deferred,
failed
metadata
object

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
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

Nationality as an ISO alpha-3 country code (e.g. MEX, USA). Users use alpha-3; recipients use alpha-2 — map accordingly.

gender
enum<string>

male, female, or other, when provided.

Available options:
male,
female,
other
residential_address
object

The individual's address. The response renests and renames the flat create-request fields: address_streetstreet_line_1, address_statesubdivision, address_zip_codepostal_code, address_citycity, address_countrycountry. Parse this nested shape — the flat address_* request fields do not round-trip.

formation_country
string
company_name
string
business_type
string
business_trade_name
string
business_description
string
business_industry
string[]
registered_address
object
physical_address
object
has_material_intermediary_ownership
boolean
account_purpose
string

Write-only in practice: accepted on create/update but currently NOT returned by GET — do not depend on reading it back.

source_of_funds
string

Write-only in practice: accepted on create/update but currently NOT returned by GET — do not depend on reading it back.

eligible_products
object[]

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.

missing_fields
object

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.

capabilities
object

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.

updated_fields
string[]

Every field present in the request body (the fields written).

requires_reverification
boolean

True when a KYC/KYB-required field for the user category changed, re-triggering verification.

verification_triggered
boolean

Whether a verification job was enqueued by this update.

warnings
string[]

Non-fatal issues (e.g. a document that failed to upload). Present only when non-empty.