Get Balance

Retrieve the current spendable balance for your organisation.

Your account can be on one of two SMS pricing modes, and the balance that is actually charged when you send depends on it:

package — sending deducts SMS credits (whole units).
fixed — sending deducts KES from your wallet.

This endpoint reports the balance for whichever mode your organisation is on (the balance + unit fields), and always includes both the wallet balance and the SMS credit balance so you never have to guess.

Endpoint

GET /v1/balance/

Authentication: Bearer API key + X-Organisation-Id (see Authentication)

Request

No request body or query parameters required.

curl https://api.v1.talkntalk.africa/v1/balance/ \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Organisation-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6"

Response

200 OK

{
  "organisation": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "pricing_mode": "package",
  "balance": "1500",
  "unit": "sms_credits",
  "wallet_balance": "250.00",
  "sms_credits": 1500,
  "currency": "KES",
  "retrieved_at": "2026-05-20T09:30:00.123456+00:00"
}

Field	Type	Description
`organisation`	string (UUID)	Your organisation's unique identifier
`pricing_mode`	string	`package` (SMS credits) or `fixed` (KES wallet)
`balance`	string	The spendable balance for the active `pricing_mode`. In `package` mode this is the number of SMS credits; in `fixed` mode it is the KES wallet balance.
`unit`	string	Unit of `balance`: `sms_credits` or `KES`
`wallet_balance`	string (decimal)	KES wallet balance — always present, regardless of mode
`sms_credits`	integer	SMS credit balance — always present, regardless of mode
`currency`	string	Wallet currency. Always `KES`
`retrieved_at`	string (ISO 8601)	Timestamp of when the balance was computed

Read pricing_mode first. If it is package, use sms_credits; if it is fixed, use wallet_balance. The balance/unit fields already resolve this for you. Do not assume balance is KES — in package mode it is a credit count.

The balance reflects all completed transactions only. Pending transactions (e.g. an in-flight SMS send) are not deducted until confirmed.

Code Examples

curl https://api.v1.talkntalk.africa/v1/balance/ \
  -H "Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Organisation-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6"

Error Responses

Status	Meaning
`401 Unauthorized`	Missing/invalid API key, or missing `X-Organisation-Id` header

{
  "detail": "Invalid or revoked API key."
}

API Keys Sender IDs