Skip to content
Unicom360
Balance

API reference

Balance

POST /api/v1/json/balance and /balance/all return how many message units are left on your bundles, so your systems can alert before a send is refused.

Balances are counted in message units: one unit is one SMS of up to 160 characters, one email, or one WhatsApp message at your plan rate. SMS and email balances are whole numbers. The WhatsApp balance can carry two decimals (37.5), because a Meta category can be priced in fractions of a unit; read it as a number, not an integer. A send that needs more units than the bundle holds is refused in full, so polling these endpoints lets you alert before that happens.

Only the API key

The API key in the header is the only credential these endpoints need. Older integrations also send username and password in the body; those fields are no longer required. If your client still sends them it keeps working: they are ignored and never stored in the request log, so remove them when convenient.

Check one bundle

POST/api/v1/json/balance

Units remaining on one bundle. Requires an API key (see Authentication).

Parameters

bundle_typeOptionalstring
SMS (default), SMS_INTERNATIONAL, EMAIL or WHATSAPP. An unknown type is not an error; it reports a balance of 0.
Example: SMS

Example request

curl -X POST https://api.unicom360.com/api/v1/json/balance \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_type": "SMS"
  }'

Responses

200 balance
{
  "status": true,
  "message": "Balance retrieved successfully",
  "balance": 1250,
  "bundle_type": "SMS",
  "client_id": "UC-00042",
  "client_name": "Acme Ltd"
}

balance is a number of message units: a whole number for SMS, SMS_INTERNATIONAL and EMAIL, and with up to two decimals for WHATSAPP (37.5), where a template category can be priced in fractions of a unit. Note the envelope: these endpoints answer with status rather than success.

Notes

  • The API key is the only credential. username and password are no longer needed in the body: integrations that still send them keep working, and both fields are ignored and never stored in the request log.

Check all bundles

POST/api/v1/json/balance/all

Units remaining on the SMS, EMAIL and WHATSAPP bundles in one call. Requires an API key (see Authentication).

Example request

curl -X POST https://api.unicom360.com/api/v1/json/balance/all \
  -H "X-API-Key: YOUR_API_KEY"

Responses

200 balances
{
  "status": true,
  "message": "All balances retrieved successfully",
  "balances": {
    "SMS": 1250,
    "EMAIL": 4000,
    "WHATSAPP": 37.5
  },
  "client_id": "UC-00042",
  "client_name": "Acme Ltd"
}

The international SMS bundle is not included here; ask for it with bundle_type SMS_INTERNATIONAL on /balance. WHATSAPP can be fractional; the other two are whole numbers.

Notes

  • The API key is the only credential. username and password are no longer needed in the body: integrations that still send them keep working, and both fields are ignored and never stored in the request log.

Bundle types

  • SMS

    Covers
    SMS to Zambian numbers (prefix 260). The default.

  • SMS_INTERNATIONAL

    Covers
    SMS to numbers outside Zambia. Only reported by /balance; not part of /balance/all.

  • EMAIL

    Covers
    Email, one unit per address.

  • WHATSAPP

    Covers
    WhatsApp templates sent from the API or the portal, priced per Meta category. Session messages, and UTILITY templates inside an open 24-hour window, are free; failed messages are refunded. Can be fractional.

The envelope here differs from the send endpoints: look at status, not success. A missing or rejected API key is the usual 401; see Errors.