REST API Platform

Callbly API Reference

Welcome to the Callbly REST API! Integrate SMS dispatching, broadcast messaging, and real-time wallet verification seamlessly into your web or mobile applications.

Interactive Playground

Enter your API token here to test live requests directly from the documentation.

Your Bearer Token

Tokens are kept in session memory only and are never saved or sent to external servers.

Authentication

The Callbly API uses Bearer Tokens to authenticate requests. Manage your tokens inside your Callbly account dashboard under API Settings.

Security Warning: Keep your tokens secure! Never publish secret tokens to public repositories or client-side JavaScript.

Always send requests over HTTPS. Include your API token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

Send Bulk SMS

POST /api/v1/sms/send-bulk

Dispatch identical SMS messages to multiple recipients in a single HTTP request. Recommended for broadcast campaigns.

Request Parameters (JSON Body)

Parameter	Type	Description
recipients	Array<String>	Required. List of recipient phone numbers (e.g., `+233201234567`).
message	String	Required. SMS body content.
sender_name	String	Required. Approved alphanumeric Sender ID (max 11 characters).

<?php
$response = Http::withToken('YOUR_API_TOKEN')
    ->acceptJson()
    ->post('https://callbly.com/api/v1/sms/send-bulk', [
        'recipients' => ['+233201234567', '+233241234567'],
        'message' => 'Hello from Callbly! This is a bulk message.',
        'sender_name' => 'MyBrand',
    ]);

if ($response->successful()) {
    echo "Message sent successfully!";
}

const axios = require('axios');

axios.post('https://callbly.com/api/v1/sms/send-bulk', {
  recipients: ['+233201234567', '+233241234567'],
  message: 'Hello from Callbly! This is a bulk message.',
  sender_name: 'MyBrand'
}, {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

import requests

url = "https://callbly.com/api/v1/sms/send-bulk"
payload = {
    "recipients": ["+233201234567", "+233241234567"],
    "message": "Hello from Callbly! This is a bulk message.",
    "sender_name": "MyBrand"
}
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Accept": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

curl -X POST "https://callbly.com/api/v1/sms/send-bulk" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
           "recipients": ["+233201234567", "+233241234567"],
           "message": "Hello from Callbly! This is a bulk message.",
           "sender_name": "MyBrand"
         }'

Recipients (comma separated)

Message

Sender Name

Response Terminal

> Ready. Awaiting request execution...

Send Single SMS

POST /api/v1/sms/send

Send an SMS message to a single recipient number.

Request Parameters (JSON Body)

Parameter	Type	Description
recipient	String	Required. A single valid phone number.
message	String	Required. SMS text message content.
sender_name	String	Required. Sender ID (max 11 characters).

<?php
$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://callbly.com/api/v1/sms/send', [
        'recipient' => '+233201234567',
        'message' => 'Hello from Callbly!',
        'sender_name' => 'MyBrand',
    ]);

curl -X POST "https://callbly.com/api/v1/sms/send" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "recipient": "+233201234567",
           "message": "Hello from Callbly!",
           "sender_name": "MyBrand"
         }'

Recipient Phone Number

Message

Sender Name

Response Terminal

> Ready. Awaiting request execution...

Check SMS Balance

GET /api/v1/sms/balance

Retrieve your remaining SMS credit balance.

<?php
$response = Http::withToken('YOUR_API_TOKEN')
    ->acceptJson()
    ->get('https://callbly.com/api/v1/sms/balance');

if ($response->successful()) {
    $balance = $response->json()['data']['balance'];
    echo "Current SMS Credits: " . $balance;
}

const axios = require('axios');

axios.get('https://callbly.com/api/v1/sms/balance', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
})
.then(response => console.log(response.data.data.balance))
.catch(error => console.error(error));

import requests

url = "https://callbly.com/api/v1/sms/balance"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json()['data']['balance'])

curl -X GET "https://callbly.com/api/v1/sms/balance" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Accept: application/json"

Fetches the current SMS credit balance associated with the Bearer token configured in the interactive playground.

Response Terminal

> Ready. Awaiting request execution...

Example JSON Response

{
  "success": true,
  "message": "SMS credit balance retrieved successfully",
  "data": {
    "balance": 500
  }
}

Check Wallet Balance

GET /api/v1/wallet/balance

Retrieve your remaining account credits and wallet balance.

<?php
$response = Http::withToken('YOUR_API_TOKEN')
    ->acceptJson()
    ->get('https://callbly.com/api/v1/wallet/balance');

if ($response->successful()) {
    $balance = $response->json()['data']['balance'];
    echo "Current Balance: ₵" . $balance;
}

const axios = require('axios');

axios.get('https://callbly.com/api/v1/wallet/balance', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
  }
})
.then(response => console.log(response.data.data.balance))
.catch(error => console.error(error));

import requests

url = "https://callbly.com/api/v1/wallet/balance"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json()['data']['balance'])

curl -X GET "https://callbly.com/api/v1/wallet/balance" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Accept: application/json"

Fetches the current wallet balance associated with the Bearer token configured in the interactive playground.

Response Terminal

> Ready. Awaiting request execution...

Example JSON Response

{
  "success": true,
  "data": {
    "balance": 1450.50,
    "currency": "GHS",
    "formatted_balance": "₵1,450.50"
  }
}

POST

Send OTP

Generate and send a One-Time Password via SMS. This endpoint will automatically deduct the necessary SMS credits.

Endpoint URL

https://callbly.com/api/v1/otp/send

Request Parameters

Parameter	Description
recipient Required	The destination phone number.
sender_name Required	An approved sender ID on your account.
length Optional	Numeric length of the OTP (4 to 8). Default is 6.
expiry Optional	Validity period in minutes. Default is 10.
message_template Optional	Custom message containing `{otp}` and `{expiry}`.

PHP (cURL)

Try it Live

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://callbly.com/api/v1/otp/send',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
    'recipient' => '233241234567',
    'sender_name' => 'Callbly',
    'length' => 6,
    'expiry' => 15
  )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_API_TOKEN',
    'Content-Type: application/json',
    'Accept: application/json'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Recipient

Sender Name

Ready. Enter parameters and send request to see JSON response...

POST

Verify OTP

Verify an OTP provided by the user using the reference returned from the Send OTP endpoint.

Endpoint URL

https://callbly.com/api/v1/otp/verify

Request Parameters

Parameter	Description
reference Required	The UUID returned from the /otp/send endpoint.
code Required	The OTP code input by the user.

PHP (cURL)

Try it Live

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://callbly.com/api/v1/otp/verify',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
    'reference' => 'uuid-from-send-endpoint',
    'code' => '123456'
  )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer YOUR_API_TOKEN',
    'Content-Type: application/json',
    'Accept: application/json'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Reference ID

Code

Ready. Enter parameters and send request to see JSON response...