Skip to content
SMSendDevelopers
Toggle colour theme

API reference

Account

Read your balance, credit limit and billing mode.

Alarm on spendable, not balance

A postpaid account is expected to run a zero or negative balance — that is what a credit limit is for. What matters is spendable, which is the balance plus the remaining credit. An alert wired to balance would page every postpaid customer continuously.

Billing models and spendable limits

PREPAID spendable = balance

Prepaid accounts draw directly from positive wallet balances. When the balance reaches zero, outbound dispatches are refused until topped up.

POSTPAID spendable = balance + credit_limit

Postpaid accounts utilize an agreed credit line (credit_limit) allowing negative wallet balances. Messages are authorized as long as spendable is positive.

Retrieve the balance

GET/public/v1/account/balance

Returns the account's wallet balance, credit limit, remaining spendable amount and billing mode.

Required scope ACCOUNT_READ

Request

curl https://api.smsend.net/public/v1/account/balance \
  -H "Authorization: Bearer $SMSEND_API_KEY"
<?php

$account = Http::withToken(getenv('SMSEND_API_KEY'))
    ->get('https://api.smsend.net/public/v1/account/balance')
    ->json('data');

if ($account['spendable'] < 50000) {
    alertLowBalance($account['spendable']);
}
const response = await fetch('https://api.smsend.net/public/v1/account/balance', {
  headers: { Authorization: `Bearer ${process.env.SMSEND_API_KEY}` },
})

const { data } = await response.json()

if (data.spendable < 50_000) {
  alertLowBalance(data.spendable)
}
import os
import requests

account = requests.get(
    "https://api.smsend.net/public/v1/account/balance",
    headers={"Authorization": f"Bearer {os.environ['SMSEND_API_KEY']}"},
).json()["data"]

if account["spendable"] < 50_000:
    alert_low_balance(account["spendable"])

Responses

200The account's financial position.
{
  "data": {
    "account_id": "01K3F5MJ0P7Q9R2S4T6V8W0X2Y",
    "billing_mode": "POSTPAID",
    "balance": -18400,
    "spendable": 231600,
    "credit_limit": 250000,
    "currency": "XOF"
  }
}

Possible errors

CodeStatusMeaning
UNAUTHORIZED401No key, a malformed key, a wrong secret, a revoked or expired key, or a suspended account. All indistinguishable by design.
INSUFFICIENT_SCOPE403The key is valid but does not carry the scope this endpoint requires. The scope is named in the detail.
RATE_LIMITED429The key's request limit was exceeded. Wait for the interval in Retry-After.
INTERNAL_ERROR500An unexpected failure on SMSend's side. Quote the request id to support.

Money

Every monetary figure the API returns is a whole number of XOF. There are no minor units and no decimals to handle: per-message prices are computed at higher precision internally and rounded exactly once, at the batch total, so the number you receive is the number that was charged.