Account Balance

TextCus Balance API allows you to retrieve your total sms, email & wallet balance information from your account. This endpoint can also help you create notifications when your balance is going low.

Endpoint

GET https://api.textcus.com/api/v2/balance

curl https://api.textcus.com/api/v2/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Headers

Authorization: Bearer API_KEY

Header Parameters

Parameters	Type	Description
apikey string	Required	Your unique API key is required to retrieve your TextCus balance

Sample Requests

PHP

<?php
$url = 'https://api.textcus.com/api/v2/balance';

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => $url,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer API_KEY' // Replace 'API_KEY' with your actual API key
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

?>

NodeJS

const axios = require('axios');

const config = {
    method: 'get',
    url: `https://api.textcus.com/api/v2/balance`,
    headers: {
        'Authorization': 'Bearer API_KEY' // Replace 'API_KEY' with your actual API key
    }
};

axios(config).then(function(response) {
    console.log(JSON.stringify(response.data));
}).catch(function(error) {
    console.error(error);
});

Python

import requests

url = f'https://api.textcus.com/api/v2/balance'

headers = {
    "Authorization": "Bearer API_KEY" # Replace 'API_KEY' with your actual API key
}

try:
    response = requests.get(url, headers=headers)
    print(response.json())
except requests.exceptions.RequestException as e:
    print(e)

Dart

import 'dart:convert';
import 'package:http/http.dart' as http;

void main() async {
  String url = 'https://api.textcus.com/api/v2/balance';

  try {
    final response = await http.get(
      Uri.parse(url),
      headers: {
        'Authorization': 'Bearer API_KEY', // Replace 'API_KEY' with your actual API Key
      },
    );

    if (response.statusCode == 200) {
      // If the server returns an OK response, parse the JSON
      print(response.body);
    } else {
      // If the server did not return a 200 OK response, throw an exception.
      print('Failed to load balance. Status code: ${response.statusCode}');
    }
  } catch (e) {
    print('Error: $e');
  }
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpHeaders;
import java.net.http.HttpResponse.BodyHandlers;

public class CheckBalance {

    public static void main(String[] args) {
        String url = "https://api.textcus.com/api/v2/balance";

        try {
            // Create HttpClient
            HttpClient client = HttpClient.newHttpClient();

            // Build the GET request
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(url))
                    .header("Authorization", "Bearer API_KEY")  // Replace 'API_KEY' with your actual API Key
                    .GET()
                    .build();

            // Send the request and get the response
            HttpResponse<String> response = client.send(request, BodyHandlers.ofString());

            // Check if the request was successful
            if (response.statusCode() == 200) {
                System.out.println("Response: " + response.body());
            } else {
                System.out.println("Failed to retrieve balance. Status code: " + response.statusCode());
                System.out.println("Response: " + response.body());
            }

        } catch (Exception e) {
            System.out.println("Error: " + e.getMessage());
        }
    }
}

VB.Net

Imports System.Net.Http
Imports System.Threading.Tasks

Module Module1
    Sub Main()
        Dim url As String = "https://api.textcus.com/api/v2/balance"

        Dim response As String = GetApiResponseAsync(url, apiKey).GetAwaiter().GetResult()

        Console.WriteLine(response)
    End Sub

    Async Function GetApiResponseAsync(url As String, apiKey As String) As Task(Of String)
        Using client As New HttpClient()
            client.DefaultRequestHeaders.Add("Authorization", "Bearer " & apiKey) ' Replace 'API_KEY' with your actual API key

            Dim response As HttpResponseMessage = Await client.GetAsync(url)
            If response.IsSuccessStatusCode Then
                Return Await response.Content.ReadAsStringAsync()
            Else
                Return "Error: " & response.StatusCode.ToString()
            End If
        End Using
    End Function
End Module

Sample Response

Success

{
  "status": true,
  "message": "Balance retrieved",
  "data": {
    "sms_rate": "0.035",
    "sms_balance": "9792",
    "email_balance": "1500",
    "wallet_balance": "250.00",
    "whatsapp_balance": "42.60"
  }
}

Errors

{
    "status": 401,
    "error": "Authentication invalid"
}, 

{
    "status": 401,
    "error": "Unauthorized: Invalid API Key"
}

Field	Unit	Notes
sms_rate	GHS	Your price per SMS credit.
sms_balance	credits	Whole SMS credits remaining, not currency.
email_balance	credits	Whole email credits remaining.
wallet_balance	GHS	Spendable cash balance.
whatsapp_balance	GHS	Separate from the wallet. See the WhatsApp API.

SMS and email balances are counts of messages. Wallet and WhatsApp balances are money in GHS. Mixing them up is the most common integration mistake here.

Check your balance on a schedule rather than before every send — one call a minute is plenty, and the send endpoints already tell you when funds run out.

---