Skip to main content
500CallsDocs
Browse the docs

Balance

You pay for messages from a prepaid naira wallet. GET /v1/balance needs the balance:read scope.

cURL
curl 'https://api.messaging.500calls.com/v1/balance' \  -H "Authorization: Bearer $API_KEY_500CALLS"
Python
import osimport requestsresponse = requests.get(    "https://api.messaging.500calls.com/v1/balance",    headers={        "Authorization": f"Bearer {os.environ['API_KEY_500CALLS']}",    },    timeout=30,)print(response.status_code, response.json())
Node.js
const response = await fetch("https://api.messaging.500calls.com/v1/balance", {  headers: {    Authorization: `Bearer ${process.env.API_KEY_500CALLS}`,  },});console.log(response.status, await response.json());
PHP
<?php$curl = curl_init('https://api.messaging.500calls.com/v1/balance');curl_setopt_array($curl, [    CURLOPT_HTTPHEADER => [        'Authorization: Bearer ' . getenv('API_KEY_500CALLS'),    ],    CURLOPT_RETURNTRANSFER => true,]);$body = curl_exec($curl);$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);echo $status, PHP_EOL, $body, PHP_EOL;

The fields

FieldMeaning
balanceAll the money in the wallet, including what is held
heldHeld for messages that are scheduled, queued or being sent, and for finished messages until they are settled, within about a minute
availablebalance minus held: what new sends can use
low_balance_thresholdYour organisation's low-balance alert threshold
as_ofWhen the balance was read

Amounts are strings with four decimal places next to "currency": "NGN": "15250.0000" is ₦15,250.00. Parse them as decimals, never as floating-point numbers.

A send's hold shows at once: straight after a 202, held includes it and available is lower by the same amount, while balance stays the same. Money charged or released when a message is sent, fails or is cancelled moves within about a minute, when the message is settled. Until then a send that needs that money can get 402 insufficient_balance.

Topping up

Top-ups happen in the dashboard, under Wallet and billing, through Paystack. The API cannot top up.