Users

Get a user

Returns the full user resource. Eligibility: eligible_products[] is populated immediately on create and on every GET — even before verification. 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 rather than populating the array. Gate your flow on status (verification_status is advisory and can contradict it). Bank intent: capabilities.requested_banks is always present, including as [] when nothing is declared — never omitted.

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-key: <api-key>'

import requests

url = "https://api.balampay.com/v1/users/{user_id}"

headers = {
    "Authorization": "Bearer <token>",
    "x-api-key": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {Authorization: 'Bearer <token>', 'x-api-key': '<api-key>'}
};

fetch('https://api.balampay.com/v1/users/{user_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.balampay.com/v1/users/{user_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.balampay.com/v1/users/{user_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.balampay.com/v1/users/{user_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

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

{
  "error": "Invalid request data",
  "details": [
    {
      "path": "user_id",
      "message": "Invalid user ID format",
      "code": "invalid_string"
    }
  ]
}

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

Stable since 2025-01-01 — unchanged in 2026-04-14.

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"

Path Parameters

user_id

string<uuid>

required

User UUID.

Response

Success.

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

Get a user

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

import requests

url = "https://api.balampay.com/v1/users/{user_id}"

headers = {
    "Authorization": "Bearer <token>",
    "x-api-key": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {Authorization: 'Bearer <token>', 'x-api-key': '<api-key>'}
};

fetch('https://api.balampay.com/v1/users/{user_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.balampay.com/v1/users/{user_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.balampay.com/v1/users/{user_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.balampay.com/v1/users/{user_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

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

{
  "error": "Invalid request data",
  "details": [
    {
      "path": "user_id",
      "message": "Invalid user ID format",
      "code": "invalid_string"
    }
  ]
}

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

Get a user

Authorizations

Headers

Path Parameters

Response