Get a user - Kira API

GET

users

{user_id}

Get a user

curl --request GET \
  --url https://api.balampay.com/v1/users/{user_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Api-Version: <x-api-version>' \
  --header 'x-api-key: <api-key>'

{
  "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.

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

Update a userFill **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` ∈ { `"U.S. Citizen"`, `"Permanent U.S. Resident"`, `"Lawful Permanent Resident of U.S."`, `"Non-Permanent U.S. Resident"`, `"Non-Resident of U.S."` } — 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.

⌘I

Get a user

curl --request GET \
  --url https://api.balampay.com/v1/users/{user_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Api-Version: <x-api-version>' \
  --header 'x-api-key: <api-key>'

{
  "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>"
}