Use these endpoints to send SMS, check balance, verify OTP codes, receive delivery updates, and connect your own app with a stable business workflow.
Use the API credentials from your Developer API page. Protected endpoints accept credentials through headers.
| Header | Required | Description |
|---|---|---|
X-API-USERNAME | Yes | Your account username. |
X-API-KEY | Yes | Your API key. |
X-API-SECRET | Yes | Your private API secret. |
| Method | Endpoint | Name | Description | Permission |
|---|---|---|---|---|
| POST | /api/send | Send SMS | Single, bulk, group and scheduled messages. | send |
| GET | /api/status | Delivery status | Check one message by SMS ID or provider ID. | reports |
| GET | /api/balance | Balance | Read wallet and SMS unit balances. | balance |
| POST | /api/otp/send | Send OTP | Create and send a verification code. | otp |
| POST | /api/otp/verify | Verify OTP | Confirm a verification code. | otp |
| POST | /api/delivery-callback | Delivery callback | Provider delivery updates receiver. | callback |
| POST | /api/webhook-test | Webhook test | Send a sample event to your webhook. | webhook |
Supports single, bulk, group and scheduled messages.
curl -X POST https://stk-push.top/api/send \
-H 'Content-Type: application/json' \
-H 'X-API-USERNAME: YOUR_USERNAME' \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'X-API-SECRET: YOUR_API_SECRET' \
-d '{"mode":"single","sender_id":"TextSMS","phone":"2547XXXXXXX","message":"Hello customer, your order is ready."}'<?php
$payload = [
'mode' => 'single',
'sender_id' => 'TextSMS',
'phone' => '2547XXXXXXX',
'message' => 'Hello customer, your order is ready.'
];
$ch = curl_init('https://stk-push.top/api/send');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-USERNAME: YOUR_USERNAME',
'X-API-KEY: YOUR_API_KEY',
'X-API-SECRET: YOUR_API_SECRET'
],
CURLOPT_POSTFIELDS => json_encode($payload)
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;const response = await fetch('https://stk-push.top/api/send', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-USERNAME': 'YOUR_USERNAME',
'X-API-KEY': 'YOUR_API_KEY',
'X-API-SECRET': 'YOUR_API_SECRET'
},
body: JSON.stringify({
mode: 'single',
sender_id: 'TextSMS',
phone: '2547XXXXXXX',
message: 'Hello customer, your order is ready.'
})
});
const data = await response.json();mode, sender_id, phone or phones, message{"success":true,"sms_id":"SMS-XXXX","status":"sent","charged":1}{"phone":"2547XXXXXXX","purpose":"login","sender_id":"TextSMS"}{"phone":"2547XXXXXXX","purpose":"login","code":"123456"}Give this URL to your SMS provider when delivery reports are available.
{"sms_id":"SMS-XXXX","phone":"2547...","status":"delivered","reason":"Delivered","time":"2026-07-20 00:12:26"}Test your API directly from this documentation page. Your credentials stay inside your browser and are sent only to your own API endpoint.
Restrict API access to trusted servers.
Limit keys to sending, balance, reports or OTP.
Protect accounts from high-volume abuse.
| HTTP | Meaning | Common fix |
|---|---|---|
| 400 | Missing or invalid fields. | Check request body. |
| 401 | Invalid API credentials. | Confirm username, key and secret. |
| 403 | Blocked by permission, IP or account status. | Review API security settings. |
| 429 | Rate limit reached. | Reduce request speed. |
| 503 | Provider or setup unavailable. | Try again or contact support. |