Skip to main content
The Kira API is versioned by date. This documentation covers version 2026-04-14 — the version we recommend you integrate against and pin to. You select a version per request with the X-Api-Version header, or you can pin your account so that version becomes its default.
This page describes API version 2026-04-14. When additional versions are published, a version selector at the top of these docs will let you switch between them.

​
How the API picks a version

For each request, Kira resolves which schema version to apply in this order:
  1. The X-Api-Version request header, when present — it always wins, even over a pinned account default.
  2. Your account’s pinned version, once you have called POST /v1/versioning/upgrade (see below).
  3. A baseline default otherwise, which may be older than the version documented here.
Because of step 3, send X-Api-Version: 2026-04-14 on every request until you pin, so you always get the schema documented on this site.

​
Send the version header

Until your account is pinned, send X-Api-Version: 2026-04-14 on every request alongside your auth headers. This tells the API which schema version to use. 
curl https://api.balampay.com/sandbox/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-api-key: $KIRA_API_KEY" \
  -H "X-Api-Version: 2026-04-14" \
  -H "Content-Type: application/json"
See Authentication for how to obtain $ACCESS_TOKEN and $KIRA_API_KEY.

​
Pin your account once

Call POST /v1/versioning/upgrade once with a target_version of 2026-04-14. This locks your account’s default to the documented schema (2026-04-14). The call is idempotent — running it again with the same target version is safe. 
curl https://api.balampay.com/sandbox/v1/versioning/upgrade \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-api-key: $KIRA_API_KEY" \
  -H "X-Api-Version: 2026-04-14" \
  -H "Content-Type: application/json" \
  -d '{
    "target_version": "2026-04-14"
  }'
Upgrades are forward-only: you can move your pin to a newer version, but the API rejects a target_version older than your current pin. A successful call returns your previous_version and current_version. After pinning, the X-Api-Version header becomes optional on subsequent requests — your account default is the pinned version. You can still send the header to override it on a per-request basis.

​
Status vocabulary depends on the version

The status values you see in responses and webhooks follow the pinned version’s vocabulary. For example, on the 2026-04-14 pin, virtual-account status is returned in lowercase (approved / rfi / deactivated).
Casing and status vocabulary vary across surfaces and versions. Always compare statuses case-insensitively, and parse the response shape rather than assuming a fixed vocabulary. See State machines & webhook catalog and Known limitations & quirks for the full picture.