Users

Create a user

Sandbox can auto-REJECT on missing KYC data: identity verification runs automatically on create (verification_triggered: true) and auto-REJECTs within seconds when required KYC data is missing (most commonly source_of_funds) (user.verification.failed webhook → terminal REJECTED; verification_status may still read unverified — gate on status). Include source_of_funds in the create payload. The rejection reason is delivered ONLY in the user.verification.failed webhook (data.reasons[]) — GET /v1/users/ never exposes it.

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-Version: <x-api-version>' \
  --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",
  "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"

Idempotency-Key

string

required

Example:

"{{idempotency_key}}"

Body

application/json

Option 1
Option 2

type

enum<string>

required

Available options:

individual

first_name

string

required

Minimum string length: 1

last_name

string

required

Minimum string length: 1

string<email>

required

verification_mode

enum<string>

Available options:

automatic,

verification_link

redirect_uri

string<uri>

language

enum<string>

Available options:

en,

es

middle_name

string

phone

string

birth_date

string

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

nationality

string

Required string length: 3

gender

enum<string>

Available options:

male,

female,

other

status

enum<string>

default:active

Available options:

active,

inactive,

suspended

external_id

string

residential_address

object

Show child attributes

address_street

string

Maximum string length: 70

address_street_2

string

Maximum string length: 70

address_city

string

address_state

string

address_zip_code

string

address_country

string

identifying_information

object[]

Show child attributes

pep_status

boolean

source_of_funds

enum<string>

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>

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

expected_monthly_volume

enum<string>

Available options:

less_than_10000,

10000_to_49999,

50000_to_199999,

200000_to_999999,

1000000_or_more

expected_transaction_count

enum<string>

Available options:

1_to_10,

11_to_50,

51_to_200,

more_than_200

employment_status

enum<string>

Available options:

employed,

self_employed,

unemployed,

retired,

student

occupation

string

current_employer

string

income_source

string

documents

object[]

Show child attributes

immigration_status

string

government_document_type

string

additional_info

object

Show child attributes

metadata

object

Show child attributes

kyc_id

string

Response

Created.

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

Get a userReturns the full user resource. **Timing:** `eligible_products[]` and `missing_fields` are empty/null on a freshly CREATED user — they populate only once verification has run. Read them AFTER the user leaves `CREATED` (or after your Kira contact flips it), not immediately after POST. Gate your flow on `status` (`verification_status` is advisory and can contradict it).

⌘I

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-Version: <x-api-version>' \
  --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",
  "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>"
}