Update a user
Updates an existing user. Every body field is optional — only the fields you send are written (partial update), even though the method is PUT.
Use PUT, NOT PATCH. PATCH /v1/users/{id} → 403 with a misleading gateway auth error (“Invalid key=value pair … in Authorization header”); it means “use PUT”, not that your Authorization header is wrong.
Primary use: fill scalar eligibility gaps after KYC so a product flips eligible: true. Read GET /v1/users/{id} first and clear the tokens in missing_fields (e.g. account_purpose, immigration_status, additional_info:has_us_bank_account). A scalar PUT clears scalar gaps but NOT document gaps — re-submit identifying_information[].documents[] for those.
Field rules:
account_purpose/source_of_fundsaccept the combined individual + business enums on update (see the schema below).expected_monthly_paymentsis a free string; useexpected_monthly_volume+expected_transaction_countfor buckets.immigration_statusis an exact string:U.S. Citizen,Permanent U.S. Resident,Lawful Permanent Resident of U.S.,Non-Permanent U.S. Resident, orNon-Resident of U.S.additional_info.has_us_bank_account/has_denied_bank_accountareYes/Nostrings (omitting them silently declaresNo).current_employeronly whenemployment_status = employed.- Do NOT send
ssnfor non-US individuals oreinfor non-US businesses (useinternational_entity_type). business_trade_nameis not updatable here;company_nameis accepted as an alias forbusiness_legal_name. The representative date-of-birth field isrepresentative_birth_date(create usesrepresentative_date_of_birth).metadatais a Stripe-style patch: keys shallow-merge, an empty-string value deletes that key, and{}clears all.
Re-verification: changing a field that is KYC/KYB-required for the user category re-triggers verification and sets requires_reverification: true in the response. verification_link users are never re-queued server-side.
Response (200) returns the user plus updated_fields (every field sent), requires_reverification, verification_triggered, eligible_products[], missing_fields, and warnings[]. Document-upload failures do not fail the call — they surface in warnings[]. A successful update emits a user.updated webhook.
Authorizations
Access token from POST /auth (the data.access_token value).
API key issued by Kira. Required on every request, including /auth.
Headers
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.
"2026-04-14"
Path Parameters
User UUID.
Body
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.
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.
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.
automatic, verification_link 11Date of birth, YYYY-MM-DD. Must be 18+.
^\d{4}-\d{2}-\d{2}$ISO alpha-3 nationality.
3male, female, other Exact string, e.g. U.S. Citizen, Permanent U.S. Resident, Non-Resident of U.S.
1Backward-compatible alias for business_legal_name.
1Legal structure (deprecated aliases accepted). Note: business_trade_name is NOT updatable via this endpoint.
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 Array of NAICS-subsector slugs.
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 ^\d{4}-\d{2}-\d{2}$3Representative date of birth, YYYY-MM-DD. On create this field is representative_date_of_birth.
^\d{4}-\d{2}-\d{2}$E.164 format, e.g. +14155551234.
3ISO alpha-3 country.
3Nested residential address (V1). You may instead use the flat address_* fields.
US individuals only — do NOT send for non-US individuals.
Brazil individual tax ID.
Mexico individual ID.
Mexico tax ID.
US businesses only — do NOT send for non-US businesses.
Brazil business tax ID.
Generic international tax ID.
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.
Combined individual + business enum.
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 Combined individual + business enum.
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 Free-form. Prefer expected_monthly_volume + expected_transaction_count.
Combined individual + business buckets.
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 Combined individual + business buckets.
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 employed, self_employed, unemployed, retired, student Send only when employment_status = employed.
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).
Whether the user is a Politically Exposed Person (PEP). Boolean — sending a string instead of a boolean is rejected with "Expected boolean, received string".
Business-only KYB attestation, Yes or No: does the business operate in a high-risk industry? Same field as CreateUserRequest.high_risk_industries.
Yes, No 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.
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.
Yes, No 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.
1Terms-of-service version the user accepted.
Free-text entity type for non-US businesses.
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).
Tax IDs and government documents to add or replace. Each entry requires type and issuing_country.
UBOs and authorized signers (businesses). Merged by email. Note the phone field here is phone_number.
Legacy flat document array. Prefer identifying_information[].documents[].
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.
User UUID.
individual or business.
individual, business Email address.
Lifecycle status: CREATED, VERIFYING, REVIEW, VERIFIED, or REJECTED. Gate product readiness on this, not on verification_status.
Creation timestamp (ISO 8601).
Last-update timestamp (ISO 8601).
KYC/KYB status: unverified, started, in_review, verified, rejected, or needs_action.
unverified, started, in_review, verified, rejected, needs_action 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.
deferred, failed Your key-value pairs, plus any client-level default metadata configured for your account (merged at create time; your request keys win on conflict).
Given name (individual users).
Family name (individual users).
Middle name (individual users), when provided.
Contact phone in E.164 form (e.g. +525512345678).
Date of birth, YYYY-MM-DD (individual users).
Nationality as an ISO alpha-3 country code (e.g. MEX, USA). Users use alpha-3; recipients use alpha-2 — map accordingly.
male, female, or other, when provided.
male, female, other 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.
Write-only in practice: accepted on create/update but currently NOT returned by GET — do not depend on reading it back.
Write-only in practice: accepted on create/update but currently NOT returned by GET — do not depend on reading it back.
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.
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.
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.
Every field present in the request body (the fields written).
True when a KYC/KYB-required field for the user category changed, re-triggering verification.
Whether a verification job was enqueued by this update.
Non-fatal issues (e.g. a document that failed to upload). Present only when non-empty.