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.
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.
Authorization: Bearer YOUR_ULTRASMS_API_KEY Accept: application/json Content-Type: application/json
API endpoints
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /sms/send | Send one or more SMS messages |
| GET | /balance | Check available SMS credits |
| GET | /sender-ids | List 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
/sms/sendProvide an approved Sender ID, recipient and message. A callback_url is optional and can be used for asynchronous status updates.
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
/balancecurl "https://ultrasms.net/api/v1/balance" \ -H "Authorization: Bearer YOUR_ULTRASMS_API_KEY"
Approved Sender IDs
/sender-idsFetch the Sender IDs available for messaging from the current account.
curl "https://ultrasms.net/api/v1/sender-ids" \ -H "Authorization: Bearer YOUR_ULTRASMS_API_KEY"
Track delivery status
/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 "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.
{
"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"
}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:
Send an order confirmation or pickup-ready message from an e-commerce backend.
Notify parents about PTA meetings, fee reminders, or school announcements.
Send a booking confirmation or appointment reminder from your application.
Send authorized campaign announcements from your voter-engagement or event system.
Send account-related alerts from a secure application backend.
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
$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)
// 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 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)
// 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
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /voice/send | Send a recorded voice campaign using multipart/form-data |
| GET | /voice/balance | Check remaining Voice minutes |
| GET | /voice/status/{campaign_id} | Check campaign and recipient status counts |
Audio requirements
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.
/api/v1/voice/sendVoice 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
| Parameter | Type | Required | Description |
|---|---|---|---|
voice_audio | File | Yes | MP3 or WAV recording within the audio limits |
recipients | String | Yes | Comma-separated Ghanaian mobile numbers (up to 5,000 valid unique numbers) |
request_key | String | Yes | Unique 32-character lowercase hexadecimal key; reuse only when retrying the same request |
callback_url | HTTPS URL | No | Receive signed recipient status updates on this campaign only |
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.
{
"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
}
}{
"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
}
}curl "https://ultrasms.net/api/v1/voice/balance" \ -H "Authorization: Bearer usms_live_YOUR_API_KEY"
{
"success": true,
"data": {
"voice_balance_minutes": 48,
"unit": "minutes"
}
}curl "https://ultrasms.net/api/v1/voice/status/VC-20261024-A1B2C3D4E5" \ -H "Authorization: Bearer usms_live_YOUR_API_KEY"
{
"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"
}
}{
"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.
// 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
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.
Sample asynchronous sms.delivered event. It is never sent by this simulator.
