Programmatic Messaging for Developers
Send transactional alerts, OTPs, balance queries, sender ID checks, and high-volume broadcasts directly from your code with our lightning-fast, high-deliverability JSON REST API.
Authentication Methods
Authenticate your API requests by providing the API Key generated in your Client Dashboard. We support 3 flexible methods:
X-Api-Key: xyz_key_YOUR_API_KEY_HERE# Method 2: Standard Bearer Token Header
Authorization: Bearer xyz_key_YOUR_API_KEY_HERE# Method 3: Query Parameter
https://api.xyzsms.com/api/sms/balance?apikey=xyz_key_YOUR_API_KEY_HERE
Core REST Endpoints
Simple, predictable HTTP endpoints with multi-language code snippets and standard JSON payloads.
/api/sms/send
Dispatches a single message or high-volume bulk broadcast to one or multiple recipient phone numbers (comma or newline separated). Units are automatically debited in real-time.
curl -X POST "https://api.xyzsms.com/api/sms/send" \
-H "X-Api-Key: xyz_key_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"senderId": "XYZSMS",
"recipients": "08012345678,08123456789",
"messageContent": "Hello! Your one-time verification code is 849201. Valid for 10 minutes."
}'
Sample JSON Response (200 OK)
{
"success": true,
"message": "Message dispatched successfully",
"totalUnitsUsed": 3.0,
"recipientsCount": 2,
"batchReference": "XYZ-TXN-840291"
}
/api/sms/balance
Queries your available SMS messaging unit balance, associated username, email, and currency.
curl -X GET "https://api.xyzsms.com/api/sms/balance" -H "X-Api-Key: xyz_key_YOUR_API_KEY"
Sample JSON Response (200 OK)
{
"success": true,
"username": "peter_onwuka",
"email": "peter@example.com",
"unitsBalance": 15240.50,
"currency": "NGN",
"serverTime": "2026-08-21T08:30:00Z"
}
/api/sms/history
Retrieves outbound message delivery logs with complete server-side pagination, total counts, and multi-parameter filters.
| Parameter | Type | Default | Description |
|---|---|---|---|
| page | integer | 1 | Page number (1-based index). |
| pageSize | integer | 50 | Number of records per page (max: 200). |
| senderId | string | null | Optional filter by Sender ID (e.g. XYZSMS). |
| recipient | string | null | Optional filter by recipient phone number. |
| status | string | null | Optional filter by status (Sent, Delivered, Failed). |
curl -X GET "https://api.xyzsms.com/api/sms/history?page=1&pageSize=20&senderId=XYZSMS" -H "X-Api-Key: xyz_key_YOUR_API_KEY"
Sample JSON Response (200 OK)
{
"success": true,
"page": 1,
"pageSize": 20,
"totalRecords": 184,
"totalPages": 10,
"hasNextPage": true,
"hasPreviousPage": false,
"records": [
{
"messageId": 2048,
"senderId": "XYZSMS",
"recipients": "08012345678",
"messageContent": "Your security OTP is 492193",
"unitsUsed": 1.5,
"status": "Sent",
"dateSent": "2026-08-21T07:50:00Z"
}
]
}
/api/sms/senderids
Retrieves all Sender IDs registered under your client account along with telecommunication operator KYC approval states.
curl -X GET "https://api.xyzsms.com/api/sms/senderids" -H "X-Api-Key: xyz_key_YOUR_API_KEY"
Sample JSON Response (200 OK)
{
"success": true,
"count": 2,
"senderIds": [
{
"id": 10,
"senderId": "XYZSMS",
"status": "Approved",
"isApproved": true,
"message": null
},
{
"id": 12,
"senderId": "MYSTORE",
"status": "Pending",
"isApproved": false,
"message": "Awaiting telecommunication operator KYC documentation review"
}
]
}
/api/sms/pricing
Retrieves base unit costs, default page rates, and real-time network pricing with international dial codes.
curl -X GET "https://api.xyzsms.com/api/sms/pricing" -H "X-Api-Key: xyz_key_YOUR_API_KEY"
Sample JSON Response (200 OK)
{
"success": true,
"currency": "NGN",
"basePricePerUnit": 2.0,
"flatUnitsPerSms": 1.0,
"count": 4,
"rates": [
{
"country": "Nigeria",
"networkProvider": "MTN",
"unitsPerSms": 1.5,
"estimatedCostPerSms": 3.0,
"internationalDialCode": "234"
},
{
"country": "Nigeria",
"networkProvider": "Airtel",
"unitsPerSms": 1.5,
"estimatedCostPerSms": 3.0,
"internationalDialCode": "234"
},
{
"country": "Nigeria",
"networkProvider": "Glo",
"unitsPerSms": 1.5,
"estimatedCostPerSms": 3.0,
"internationalDialCode": "234"
},
{
"country": "Nigeria",
"networkProvider": "9mobile",
"unitsPerSms": 1.5,
"estimatedCostPerSms": 3.0,
"internationalDialCode": "234"
}
]
}