Users

Update a user

Fill scalar eligibility fields after KYC so a product flips eligible: true. Run this once you’ve read GET /v1/users/{id} and seen tokens in missing_fields (e.g. account_purpose, immigration_status, additional_info:has_us_bank_account).

Use PUT, NOT PATCH. PUT /v1/users/{id} → 200 (smoke-confirmed); PATCH /v1/users/{id} → 403 (not a route). The PATCH 403 body is a misleading gateway-level auth error (“Invalid key=value pair … in Authorization header”) — it means “PATCH is not supported, use PUT”; it does NOT mean your Authorization header is wrong.

Field rules:

account_purpose must be one of: 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 (any other value → 400 invalid_enum_value).
immigration_status ∈ — exact strings.
additional_info.has_us_bank_account / has_denied_bank_account = "yes" / "no" strings (omitting them silently declares “no”).
current_employer only when employment_status = "employed".
Do NOT send ssn for non-US individuals; do NOT send ein for non-US businesses (use international_entity_type).

Scope: a scalar PUT clears scalar gaps but NOT document gaps — documents are file uploads (re-submit identifying_information[].documents[] to clear those). After the PUT, re-read GET /v1/users/{id} and confirm eligible_products[] / missing_fields updated.

PUT

users

{user_id}

Update a user

curl --request PUT \
  --url https://api.balampay.com/v1/users/{user_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Version: <x-api-version>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "immigration_status": "Non-Resident of U.S.",
  "additional_info": {
    "has_us_bank_account": "no",
    "has_denied_bank_account": "no"
  },
  "current_employer": "Acme",
  "account_purpose": "receive_payments",
  "occupation": "Engineer"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "email": "jsmith@example.com",
  "status": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "verification_status": "unverified",
  "verification_mode": "<string>",
  "verification_link": "<string>",
  "verification_link_error": "<string>",
  "metadata": {},
  "first_name": "<string>",
  "last_name": "<string>",
  "middle_name": "<string>",
  "phone": "<string>",
  "birth_date": "<string>",
  "nationality": "<string>",
  "residential_address": {
    "street_line_1": "<string>",
    "street_line_2": "<string>",
    "city": "<string>",
    "subdivision": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "formation_country": "<string>",
  "business_legal_name": "<string>",
  "company_name": "<string>",
  "business_type": "<string>",
  "business_trade_name": "<string>",
  "business_description": "<string>",
  "business_industry": [
    "<string>"
  ],
  "signed_agreement_id": "<string>",
  "registered_address": {
    "street_line_1": "<string>",
    "street_line_2": "<string>",
    "city": "<string>",
    "subdivision": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "physical_address": {
    "street_line_1": "<string>",
    "street_line_2": "<string>",
    "city": "<string>",
    "subdivision": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "has_material_intermediary_ownership": true,
  "account_purpose": "<string>",
  "source_of_funds": "<string>"
}

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

required

Example:

"2026-04-14"

Path Parameters

user_id

string<uuid>

required

User UUID.

Body

application/json

The body is of type object.

Response

Success.

string<uuid>

required

type

enum<string>

required

Available options:

individual,

business

string<email>

required

status

string

required

created_at

string<date-time>

required

updated_at

string<date-time>

required

verification_status

enum<string>

default:unverified

Available options:

unverified,

started,

in_review,

verified,

rejected,

needs_action

verification_mode

string

verification_link

string

verification_link_error

string

metadata

object

Show child attributes

first_name

string

last_name

string

middle_name

string

phone

string

birth_date

string

nationality

string

gender

enum<string>

Available options:

male,

female,

other

residential_address

object

Show child attributes

formation_country

string

business_legal_name

string

company_name

string

business_type

string

business_trade_name

string

business_description

string

business_industry

string[]

signed_agreement_id

string

registered_address

object

Show child attributes

physical_address

object

Show child attributes

has_material_intermediary_ownership

boolean

account_purpose

string

source_of_funds

string

Re-issue verificationRe-trigger KYC/KYB for a user that came back **REJECTED**, without re-creating them. `type` selects how the user completes verification: - `"embedded-link"` (this example) — Kira returns a **hosted KYC link** (`verification_link` in the response); your end user opens it and completes verification on Kira's page. Same flow as `verification_mode: "verification_link"` on Create User. - `"api"` — **you** submit the corrected KYC data yourself via a `metadata` object. Same flow as `verification_mode: "automatic"` on Create User. Requires the `Idempotency-Key` header. Note: this endpoint does **not** accept `verification_mode` — that field belongs to Create User (`POST /v1/users`).

⌘I

Update a user

curl --request PUT \
  --url https://api.balampay.com/v1/users/{user_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Version: <x-api-version>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "immigration_status": "Non-Resident of U.S.",
  "additional_info": {
    "has_us_bank_account": "no",
    "has_denied_bank_account": "no"
  },
  "current_employer": "Acme",
  "account_purpose": "receive_payments",
  "occupation": "Engineer"
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "email": "jsmith@example.com",
  "status": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "verification_status": "unverified",
  "verification_mode": "<string>",
  "verification_link": "<string>",
  "verification_link_error": "<string>",
  "metadata": {},
  "first_name": "<string>",
  "last_name": "<string>",
  "middle_name": "<string>",
  "phone": "<string>",
  "birth_date": "<string>",
  "nationality": "<string>",
  "residential_address": {
    "street_line_1": "<string>",
    "street_line_2": "<string>",
    "city": "<string>",
    "subdivision": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "formation_country": "<string>",
  "business_legal_name": "<string>",
  "company_name": "<string>",
  "business_type": "<string>",
  "business_trade_name": "<string>",
  "business_description": "<string>",
  "business_industry": [
    "<string>"
  ],
  "signed_agreement_id": "<string>",
  "registered_address": {
    "street_line_1": "<string>",
    "street_line_2": "<string>",
    "city": "<string>",
    "subdivision": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "physical_address": {
    "street_line_1": "<string>",
    "street_line_2": "<string>",
    "city": "<string>",
    "subdivision": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "has_material_intermediary_ownership": true,
  "account_purpose": "<string>",
  "source_of_funds": "<string>"
}