Users

Create a user

Creates an end client (your user) and starts identity verification — KYC for individual, KYB for business. The required field set depends on type (individual | business) and address_country (ISO alpha-3, e.g. USA, MEX). See Creating users for the full per-category field tables, conditional rules, and country restrictions.

Required to create: individuals need type, first_name, last_name, email; businesses need type, business_legal_name, email. A bare payload returns 201, but the user will not be product-eligible.

The Idempotency-Key header is required and must be a UUID; reusing a key with a different body returns 409.

Enums differ by type. account_purpose accepts 14 values for individuals and 8 (different) values for businesses; source_of_funds, expected_monthly_volume, and expected_transaction_count likewise differ between individuals and businesses. expected_monthly_payments is a free-form string on this endpoint — use expected_monthly_volume + expected_transaction_count for bucketed values. Any out-of-set value → 400 invalid_enum_value.

Verification modes (verification_mode):

automatic (default) — verification runs on create and you receive user.* webhooks. Send source_of_funds and the full category field set.
verification_link — every other field is stripped and a hosted KYC URL is returned as verification_link. Pass redirect_uri to control the post-completion redirect and language (en/es) for the form locale. The created user echoes placeholder values for the stripped fields (nationality: "---", birth_date: "1900-01-01", empty residential_address) until the hosted flow completes — treat eligible_products[].missing_fields as the authoritative outstanding-fields signal, not the echoed field values.

Documents (identifying_information[].documents[].file) accept a base64 data URI (JPEG/PNG/PDF) or — on version 2026-04-14+ — an https:// URL (http:// is rejected). A two-sided ID (any type except passport/visa) that includes a front must also include a back. The whole request body is capped at 10 MB and inline base64 counts against it (≈ +33% overhead), so prefer the https:// URL form for large files — it’s fetched asynchronously, doesn’t count toward the body limit, and accepts files up to 30 MB each.

Sandbox verification behavior: identity verification triggers automatically once the user is complete for at least one product (verification_triggered: true) and the sandbox approves within seconds — no manual step. An incomplete user is NOT rejected: verification does not trigger and the user stays CREATED with the gaps listed in missing_fields. A terminal REJECTED means the provider evaluated the submitted data and declined it (user.verification.failed webhook; verification_status may still read unverified — gate on status). The rejection reason is delivered ONLY in the user.verification.failed webhook (data.reasons[]) — GET /v1/users/{id} never exposes it. A data rejection is distinct from a verification-provider call failure (network / 5xx / timeout reaching the provider): a call failure is a retryable system error — the user stays non-terminal (VERIFYING), no user.verification.failed fires, and the transition surfaces via user.status_changed.

Response (201) returns the user plus verification_triggered, eligible_products[], missing_fields (per-product field tokens; populated once verification has run), verification_link (link mode only), and warnings[] (non-fatal document-upload issues).

POST

users

curl --request POST \
  --url https://api.balampay.com/v1/users \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "type": "individual",
  "verification_mode": "automatic",
  "first_name": "Maria",
  "last_name": "Gonzalez",
  "birth_date": "1990-05-15",
  "email": "maria.test+1782336813@example.com",
  "phone": "+525512345678",
  "nationality": "MEX",
  "address_street": "Av. Reforma 123",
  "address_city": "Ciudad de Mexico",
  "address_state": "CDMX",
  "address_zip_code": "06600",
  "address_country": "MEX",
  "document_type": "passport",
  "document_number": "G12345678",
  "document_country": "MEX",
  "immigration_status": "Non-Resident of U.S.",
  "employment_status": "employed",
  "current_employer": "Self",
  "occupation": "Software Engineer",
  "account_purpose": "receive_payments",
  "source_of_funds": "salary",
  "identifying_information": [
    {
      "type": "passport",
      "issuing_country": "MEX",
      "number": "G12345678",
      "expiration": "2030-05-15",
      "documents": [
        {
          "type": "front",
          "file": "data:image/jpeg;base64,PLACEHOLDER"
        }
      ]
    }
  ],
  "additional_info": {
    "has_us_bank_account": "No",
    "has_denied_bank_account": "No"
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "individual",
  "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>",
  "verification_link_error_severity": "deferred",
  "metadata": {},
  "first_name": "<string>",
  "last_name": "<string>",
  "middle_name": "<string>",
  "phone": "<string>",
  "birth_date": "<string>",
  "nationality": "<string>",
  "gender": "male",
  "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>"
  ],
  "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>",
  "eligible_products": [
    {
      "product_id": "<string>",
      "product_code": "<string>",
      "product_name": "<string>",
      "eligible": true,
      "missing_fields": [
        "<string>"
      ],
      "unsupported_reason": "enhanced_due_diligence_required"
    }
  ],
  "missing_fields": {},
  "capabilities": {
    "requested_banks": [
      "<string>"
    ]
  },
  "verification_triggered": true,
  "warnings": [
    "<string>"
  ]
}

{
  "code": "<string>",
  "message": "<string>",
  "error": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ],
  "details": "<array>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

Changed in this version.

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-04-14"

Idempotency-Key

string<uuid>

required

Example:

"{{idempotency_key}}"

Body

application/json

Option 1
Option 2

type

enum<string>

required

Discriminator: individual (KYC) or business (KYB). Selects the required fields and which enum sets apply.

Available options:

individual

first_name

string

required

Given name. Required for individuals.

Minimum string length: 1

last_name

string

required

Family name. Required for individuals.

Minimum string length: 1

string<email>

required

Email address. Required for all users.

verification_mode

enum<string>

automatic (default) runs verification on create and emits user.* webhooks. verification_link returns a hosted KYC URL and strips every other field.

Available options:

automatic,

verification_link

capabilities

object

Per-subclient bank intent — records which bank(s) this subclient plans to use, distinct from bank-account authorization (which lives in your account's own configuration). Optional; omit it to use the standard verification path.

Show child attributes

redirect_uri

string<uri>

Where the hosted verification form redirects after completion. Used only with verification_mode: verification_link.

language

enum<string>

Locale for the hosted verification form: en or es. Used only with verification_mode: verification_link.

Available options:

en,

es

middle_name

string

Middle name.

phone

string

Phone in E.164 format, e.g. +14155551234. Spaces and dashes are sanitized before validation.

birth_date

string

Date of birth, YYYY-MM-DD. The user must be at least 18 years old.

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

nationality

string

Nationality as an ISO 3166-1 alpha-3 code (e.g. USA, MEX).

Required string length: 3

gender

enum<string>

One of male, female, other.

Available options:

male,

female,

other

status

enum<string>

default:active

Ignored on create — new users always start as CREATED.

Available options:

active,

inactive,

suspended

external_id

string

Your own reference ID for this user (stored as partnerUserId).

residential_address

object

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

Show child attributes

address_street

string

Street address (≤ 70 chars). Flat (V2) address form.

Maximum string length: 70

address_street_2

string

Apartment, suite, or unit (≤ 70 chars).

Maximum string length: 70

address_city

string

City.

address_state

string

State or province (US state for USA users).

address_zip_code

string

ZIP or postal code.

address_country

string

Country as ISO alpha-3. With type, selects the user category; users in restricted countries are not VA-eligible.

identifying_information

object[]

Tax IDs and government documents. Each entry requires type and issuing_country.

Show child attributes

pep_status

boolean

Whether the user is a Politically Exposed Person.

tos_accepted_version

string

Terms-of-service version the user accepted. Kira stamps tos_accepted_at on receipt.

source_of_funds

enum<string>

Origin of funds. The accepted enum differs for individuals vs businesses.

Available options:

salary,

self_employment_income,

investment_proceeds,

savings_inheritance_gift,

gifts,

inheritance,

investments_loans,

pension_retirement,

sale_of_assets_real_estate,

savings,

someone_elses_funds

account_purpose

enum<string>

Intended account use. 14 values for individuals, 8 (different) values for businesses.

Available options:

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

expected_monthly_payments

string

Free-form string. Prefer expected_monthly_volume + expected_transaction_count for bucketed values.

expected_monthly_volume

enum<string>

Expected monthly volume bucket. Buckets differ for individuals vs businesses.

Available options:

less_than_10000,

10000_to_49999,

50000_to_199999,

200000_to_999999,

1000000_or_more

expected_transaction_count

enum<string>

Expected monthly transaction-count bucket. Buckets differ for individuals vs businesses.

Available options:

1_to_10,

11_to_50,

51_to_200,

more_than_200

employment_status

enum<string>

One of employed, self_employed, unemployed, retired, student.

Available options:

employed,

self_employed,

unemployed,

retired,

student

occupation

string

Occupation. Required (for eligibility) when employment_status = employed.

current_employer

string

Employer. Required (for eligibility) when employment_status = employed.

income_source

string

Income source. Required (for eligibility) unless employment_status = employed.

documents

object[]

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

Show child attributes

immigration_status

string

Exact string, e.g. U.S. Citizen, Permanent U.S. Resident, Non-Resident of U.S. Required for international individuals.

government_document_type

string

additional_info

object

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

Show child attributes

metadata

object

Your key-value pairs. ≤ 50 keys; key 1–40 chars with no [ or ]; value ≤ 500 chars. Kira can additionally configure client-level default metadata for your account; defaults are merged in at create time (your keys win on conflict), so the stored and returned metadata may include keys you did not send.

Show child attributes

kyc_id

string

Optional partner-supplied KYC session ID.

Response

Created.

The created user plus create-time verification details.

string<uuid>

required

User UUID.

type

enum<string>

required

individual or business.

Available options:

individual,

business

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.

verification_link

string

Hosted KYC URL — present only in verification_link mode.

verification_link_error

string

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.

verification_link_error_severity

enum<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).

Show child attributes

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

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

registered_address

object

Show child attributes

physical_address

object

Show child attributes

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.

Show child attributes

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.

Show child attributes

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.

Show child attributes

verification_triggered

boolean

Whether a KYC/KYB verification job was enqueued on create.

warnings

string[]

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

curl --request POST \
  --url https://api.balampay.com/v1/users \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "type": "individual",
  "verification_mode": "automatic",
  "first_name": "Maria",
  "last_name": "Gonzalez",
  "birth_date": "1990-05-15",
  "email": "maria.test+1782336813@example.com",
  "phone": "+525512345678",
  "nationality": "MEX",
  "address_street": "Av. Reforma 123",
  "address_city": "Ciudad de Mexico",
  "address_state": "CDMX",
  "address_zip_code": "06600",
  "address_country": "MEX",
  "document_type": "passport",
  "document_number": "G12345678",
  "document_country": "MEX",
  "immigration_status": "Non-Resident of U.S.",
  "employment_status": "employed",
  "current_employer": "Self",
  "occupation": "Software Engineer",
  "account_purpose": "receive_payments",
  "source_of_funds": "salary",
  "identifying_information": [
    {
      "type": "passport",
      "issuing_country": "MEX",
      "number": "G12345678",
      "expiration": "2030-05-15",
      "documents": [
        {
          "type": "front",
          "file": "data:image/jpeg;base64,PLACEHOLDER"
        }
      ]
    }
  ],
  "additional_info": {
    "has_us_bank_account": "No",
    "has_denied_bank_account": "No"
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "type": "individual",
  "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>",
  "verification_link_error_severity": "deferred",
  "metadata": {},
  "first_name": "<string>",
  "last_name": "<string>",
  "middle_name": "<string>",
  "phone": "<string>",
  "birth_date": "<string>",
  "nationality": "<string>",
  "gender": "male",
  "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>"
  ],
  "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>",
  "eligible_products": [
    {
      "product_id": "<string>",
      "product_code": "<string>",
      "product_name": "<string>",
      "eligible": true,
      "missing_fields": [
        "<string>"
      ],
      "unsupported_reason": "enhanced_due_diligence_required"
    }
  ],
  "missing_fields": {},
  "capabilities": {
    "requested_banks": [
      "<string>"
    ]
  },
  "verification_triggered": true,
  "warnings": [
    "<string>"
  ]
}

{
  "code": "<string>",
  "message": "<string>",
  "error": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ],
  "details": "<array>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

Authentication

Versioning

Users

Virtual Accounts

Quotations

Payouts

Recipients

Reference

Create a user

Authorizations

Headers

Body

Response