UltraSMS
SAB-TECH HUB · Developer Resources

UltraSMS API Documentation

Integrate SMS and recorded Voice messaging into your website or application. Explore separate API references, secure authentication, credit balances, delivery tracking, and callbacks.

Base URLhttps://ultrasms.net/api/v1

Getting started

Sign in to your UltraSMS customer account, open Developers → API Keys and create a Live or Test key. Use the key on your server when making API requests.

Test and Live modes: use a Test key while building, then switch to a Live key when ready to send real messages. API keys and SMS credits are managed in your customer dashboard.

Authentication

Supply your API key in the Authorization header. Treat it like a password and never publish it in browser-side code or a mobile app.

HTTP headers
Authorization: Bearer YOUR_ULTRASMS_API_KEY
Accept: application/json
Content-Type: application/json

API endpoints

MethodEndpointPurpose
POST/sms/sendSend one or more SMS messages
GET/balanceCheck available SMS credits
GET/sender-idsList approved Sender IDs
GET/sms/status/{message_id}Retrieve message delivery status

All paths are relative to the base URL above. Access permissions and response fields depend on the API key and current account configuration.

Send SMS

POST/sms/send

Provide an approved Sender ID, recipient and message. A callback_url is optional and can be used for asynchronous status updates.

cURL
curl -X POST "https://ultrasms.net/api/v1/sms/send" \
  -H "Authorization: Bearer YOUR_ULTRASMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "MYSHOP",
    "recipient": "233241234567",
    "message": "Your order has been confirmed.",
    "callback_url": "https://example.com/webhooks/ultrasms"
  }'

Remove callback_url entirely if your system does not need webhooks.

Check SMS balance

GET/balance
cURL
curl "https://ultrasms.net/api/v1/balance" \
  -H "Authorization: Bearer YOUR_ULTRASMS_API_KEY"

Approved Sender IDs

GET/sender-ids

Fetch the Sender IDs available for messaging from the current account.

cURL
curl "https://ultrasms.net/api/v1/sender-ids" \
  -H "Authorization: Bearer YOUR_ULTRASMS_API_KEY"

Track delivery status

GET/sms/status/{message_id}

Check status even when your original send request did not include a callback URL. Sent means submitted to the provider; it does not guarantee a delivery confirmation.

cURL
curl "https://ultrasms.net/api/v1/sms/status/USMS_MESSAGE_ID" \
  -H "Authorization: Bearer YOUR_ULTRASMS_API_KEY"

Optional delivery callbacks

When you include an HTTPS callback_url in a send request, UltraSMS can POST delivery events to your application. Callback events may arrive later than the initial send response.

Sample webhook JSON
{
  "event": "sms.delivered",
  "message_id": "CMP-8F3A91D2",
  "sender_id": "MYSHOP",
  "recipient": "233241234567",
  "status": "delivered",
  "delivered_at": "2026-10-01T22:01:17+00:00",
  "timezone": "Africa/Accra"
}
Verify the X-UltraSMS-Signature header using HMAC-SHA256 over X-UltraSMS-Timestamp + "." + raw_request_body, with the callback signing secret from your customer dashboard.

Real-world integration scenarios

Examples of how businesses can use UltraSMS in their existing systems:

Order notifications

Send an order confirmation or pickup-ready message from an e-commerce backend.

School communications

Notify parents about PTA meetings, fee reminders, or school announcements.

Appointments & reminders

Send a booking confirmation or appointment reminder from your application.

Campaign updates

Send authorized campaign announcements from your voter-engagement or event system.

Account notifications

Send account-related alerts from a secure application backend.

Before sending, obtain appropriate recipient consent, use your approved Sender ID, check available credits, and handle asynchronous delivery statuses.

Integration examples by language

These examples send a single SMS through the UltraSMS REST API. Replace the sample Sender ID and recipient. Configure the Live API key securely on your server.

PHP (cURL)

PHP
<?php
$apiKey = getenv('ULTRASMS_API_KEY');
$payload = [
    'sender_id' => 'MYSHOP',
    'recipient' => '233241234567',
    'message' => 'Your order has been confirmed.'
];
$ch = curl_init('https://ultrasms.net/api/v1/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
$result = json_decode($response, true);
if ($status < 200 || $status >= 300) {
    throw new RuntimeException('UltraSMS API error: ' . $response);
}
print_r($result);

Node.js (fetch)

JavaScript
// Node.js 18+ (built-in fetch)
const apiKey = process.env.ULTRASMS_API_KEY;
const response = await fetch('https://ultrasms.net/api/v1/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sender_id: 'MYSHOP',
    recipient: '233241234567',
    message: 'Your order has been confirmed.'
  })
});
const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
console.log(result);

Python (requests)

Python
# Python 3 with requests: pip install requests
import os
import requests

url = 'https://ultrasms.net/api/v1/sms/send'
response = requests.post(
    url,
    headers={'Authorization': f"Bearer {os.environ['ULTRASMS_API_KEY']}"},
    json={
        'sender_id': 'MYSHOP',
        'recipient': '233241234567',
        'message': 'Your order has been confirmed.'
    },
    timeout=30
)
response.raise_for_status()
print(response.json())

Browser JavaScript (secure pattern)

JavaScript
// Browser-safe architecture: call your OWN backend.
// Never expose an UltraSMS Live API key in frontend code.
const response = await fetch('/api/send-order-update', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({order_id: 'ORDER-123'})
});
if (!response.ok) throw new Error('Unable to request SMS');
console.log(await response.json());
// Your backend validates the order, then calls UltraSMS.

Errors & security

Handle unsuccessful HTTP responses gracefully, validate recipients, respect rate limits, and retry only when appropriate. Common causes include an invalid API key, insufficient permission, an unapproved Sender ID or a rate limit.

Keep API keys on your server, use HTTPS, and never embed them into publicly accessible JavaScript or Flutter application source.

Open the customer dashboard documentation for additional account-specific instructions.

Voice Messaging API

Send recorded Voice calls through UltraSMS using the same Bearer API keys used for SMS. Voice requires an active Voice Plan, enabled Voice access, and the applicable account verification. Test keys validate without sending calls or deducting minutes.

Voice endpoints

MethodEndpointPurpose
POST/voice/sendSend a recorded voice campaign using multipart/form-data
GET/voice/balanceCheck remaining Voice minutes
GET/voice/status/{campaign_id}Check campaign and recipient status counts

Audio requirements

Accepted formats: MP3, uncompressed PCM WAV or G.711 A-law WAV. Recommended: 8,000 Hz, mono, 8-bit G.711 A-law WAV. Duration: 1–120 seconds. Maximum audio file: 1,048,576 bytes (1 MiB). Audio that exceeds these limits is rejected before billing.

Each started minute is billed per valid unique recipient. Up to 5,000 valid unique Ghanaian numbers may be sent in one campaign. Invalid numbers are skipped and reported in the response.

Send Voice

Submit an audio recording to one or more recipients using multipart/form-data. File uploads are not supported in a JSON request body.

POST /api/v1/voice/send

Voice delivery callbacks (optional)

Add callback_url to your Voice send request to receive a signed status notification for each recipient when Arkesel reports a status change. No developer callback is sent if omitted. This URL must be a publicly reachable HTTPS endpoint. Voice callbacks are independent from SMS webhooks and do not initiate call retries.

POST https://example.com/webhooks/voice
Content-Type: application/json
X-UltraSMS-Event: voice.answered
X-UltraSMS-Timestamp: 1792864800
X-UltraSMS-Signature: sha256=SIGNATURE

{
  "event": "voice.answered",
  "campaign_id": "VC-20261024-A1B2C3D4E5",
  "recipient": "233241234567",
  "status": "ANSWERED",
  "timestamp": "2026-10-24T14:00:00+00:00",
  "timezone": "Africa/Accra"
}

Signature: HMAC-SHA256 of timestamp + "." + raw JSON body using the customer's optional callback signing key, available under API Keys. Compare signatures using a constant-time function. Reply with HTTP 2xx. Failed deliveries are retried separately, up to five attempts. Events may be duplicated or received later than their status transition; handle callbacks idempotently. Examples are illustrative.

Request parameters

ParameterTypeRequiredDescription
voice_audioFileYesMP3 or WAV recording within the audio limits
recipientsStringYesComma-separated Ghanaian mobile numbers (up to 5,000 valid unique numbers)
request_keyStringYesUnique 32-character lowercase hexadecimal key; reuse only when retrying the same request
callback_urlHTTPS URLNoReceive signed recipient status updates on this campaign only
Request example · cURL
curl --request POST 'https://ultrasms.net/api/v1/voice/send' \
  --header 'Authorization: Bearer YOUR_ULTRASMS_API_KEY' \
  --form 'recipients=0241234567,0551234567' \
  --form 'voice_audio=@greeting.wav;type=audio/wav' \
  --form 'request_key=0123456789abcdef0123456789abcdef' \
  --form 'callback_url=https://example.com/webhooks/voice'

@greeting.wav means a file on the developer's computer or server. cURL builds the multipart request automatically; do not manually set Content-Type: application/json. Protect your API key on the server.

Accepted live requests return a campaign identifier and queued status. Queued does not mean delivered. Use the campaign status endpoint to monitor progress. Arkesel manages provider-side retries; UltraSMS does not automatically repeat uncertain calls.

Requests & Responses

The examples below show the response structure. Campaign IDs, balances, counts, and timestamps are illustrative. Voice minutes are independent of SMS credits.

Send · HTTP 202
{
  "success": true,
  "message": "Voice campaign queued. Provider delivery is asynchronous; use the status endpoint.",
  "data": {
    "campaign_id": "VC-20261024-A1B2C3D4E5",
    "status": "queued",
    "provider_campaign_id": null,
    "duration_seconds": 42,
    "recipients": 2,
    "minutes_charged": 2,
    "recipient_status_counts": {"queued": 2},
    "created_at": "2026-10-24T14:00:00+00:00",
    "invalid_numbers_skipped": 1,
    "voice_balance_minutes": 48
  }
}
Voice send · Test key · HTTP 200
{
  "success": true,
  "message": "Test validated; no calls submitted or Voice minutes charged.",
  "data": {
    "status": "test",
    "recipients": 2,
    "invalid_numbers_skipped": 1,
    "duration_seconds": 42,
    "estimated_minutes": 2,
    "voice_balance_minutes": 50
  }
}
Balance · Request
curl "https://ultrasms.net/api/v1/voice/balance" \
  -H "Authorization: Bearer usms_live_YOUR_API_KEY"
Balance · HTTP 200
{
  "success": true,
  "data": {
    "voice_balance_minutes": 48,
    "unit": "minutes"
  }
}
Status · Request
curl "https://ultrasms.net/api/v1/voice/status/VC-20261024-A1B2C3D4E5" \
  -H "Authorization: Bearer usms_live_YOUR_API_KEY"
Status · HTTP 200
{
  "success": true,
  "data": {
    "campaign_id": "VC-20261024-A1B2C3D4E5",
    "status": "queued",
    "provider_campaign_id": null,
    "duration_seconds": 42,
    "recipients": 2,
    "minutes_charged": 2,
    "recipient_status_counts": {"queued": 2},
    "created_at": "2026-10-24T14:00:00+00:00"
  }
}
Voice error · HTTP 402
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_VOICE_BALANCE",
    "message": "Insufficient Voice Balance."
  }
}

JavaScript — convert audio in the browser

This example converts supported browser-decodable audio to a compact 8 kHz mono A-law WAV file, without server-side FFmpeg. Upload the result to your own backend and have the backend call UltraSMS. Never expose your Live API key in browser JavaScript.

JavaScript · Browser audio conversion
// Input: audio File from <input type="file" accept="audio/*">
async function convertToVoiceWav(file, maxSeconds = 120) {
  const ctx = new (window.AudioContext || window.webkitAudioContext)();
  try {
    const decoded = await ctx.decodeAudioData(await file.arrayBuffer());
    if (decoded.duration < 1 || decoded.duration > maxSeconds)
      throw new Error(`Audio must be 1–${maxSeconds} seconds`);
    const rate = 8000, count = Math.ceil(decoded.duration * rate);
    const offline = new OfflineAudioContext(1, count, rate);
    const source = offline.createBufferSource();
    source.buffer = decoded;
    // OfflineAudioContext mixes source channels to one mono channel.
    source.connect(offline.destination);
    source.start();
    const rendered = await offline.startRendering();
    const samples = rendered.getChannelData(0);
    const output = new Uint8Array(58 + samples.length);
    const view = new DataView(output.buffer);
    function word(pos, text) { for (let i=0; i<text.length; i++) output[pos+i]=text.charCodeAt(i); }
    word(0,'RIFF'); view.setUint32(4,output.length-8,true);
    word(8,'WAVE'); word(12,'fmt '); view.setUint32(16,18,true);
    view.setUint16(20,6,true);  // WAVE_FORMAT_ALAW
    view.setUint16(22,1,true);  // mono
    view.setUint32(24,rate,true); view.setUint32(28,rate,true);
    view.setUint16(32,1,true); view.setUint16(34,8,true);
    view.setUint16(36,0,true); // cbSize
    word(38,'fact'); view.setUint32(42,4,true);
    view.setUint32(46,samples.length,true);
    word(50,'data'); view.setUint32(54,samples.length,true);
    function aLaw(sample) {
      let pcm = Math.max(-32768,Math.min(32767,Math.round(sample*32767)));
      const mask = pcm >= 0 ? 0xD5 : 0x55;
      if (pcm < 0) pcm = -pcm-1;
      pcm = Math.min(pcm,32767);
      let value;
      if (pcm < 256) value = pcm >> 4;
      else {
        let segment = 1;
        for (let x=pcm >> 8; x > 1; x >>= 1) segment++;
        value = (segment << 4) | ((pcm >> (segment+3)) & 15);
      }
      return value ^ mask;
    }
    for (let i=0; i<samples.length; i++) output[58+i]=aLaw(samples[i]);
    const blob = new Blob([output], {type:'audio/wav'});
    if (blob.size > 1048576) throw new Error('Converted audio is too large');
    return new File([blob], 'voice-message.wav', {type:'audio/wav'});
  } finally { await ctx.close(); }
}
// const wav = await convertToVoiceWav(fileInput.files[0]);
// Send wav to YOUR backend, which securely calls POST /api/v1/voice/send.

Browser decoding depends on the original audio format. Check the converted file with a short test call before sending a large campaign.

API Simulator

Try an API request

Demo only
REQUEST PARAMETERS

Edit sample data

Only include this if your application needs asynchronous delivery updates. Without it, the API returns its normal response and sends no webhook.

01 / CLIENTRequest
POST/api/v1/sms/send
Request preview
02 / SERVERResponse
Not run yetDEMO RESPONSE
Response previewJSON
Ready to simulate
Status codes and delivery details are illustrative. No SMS is sent.
Demonstration only. No external requests, credentials, SMS credits, or webhooks are used. Values and balances are illustrative; live responses depend on your account.Get your API key →
Integrate with your own application.Use Test keys in your account for API validation without SMS charges, then switch to Live keys when ready. Developer documentation is available after signing in.
Create developer account