REST API v1.1.0

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.

Get Your Free API Key Explore 5 Endpoints Interactive Studio

Authentication Methods

Authenticate your API requests by providing the API Key generated in your Client Dashboard. We support 3 flexible methods:

# Method 1: Custom Header (Recommended)
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.

POST

/api/sms/send

Single & Bulk Dispatch

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"
}
GET

/api/sms/balance

Real-Time Wallet

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"
}
GET

/api/sms/history

Paginated & Filterable

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"
    }
  ]
}
GET

/api/sms/senderids

Sender Verification

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"
    }
  ]
}
GET

/api/sms/pricing

Live Rates & Carriers

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"
    }
  ]
}