Developer API

SMS API documentation for your website integration

Email API Documentation

Use these endpoints to send SMS, check balance, verify OTP codes, receive delivery updates, and connect your own app with a stable business workflow.

SMS Sending
Single, bulk, groups and schedule
Clear Examples
cURL, PHP and JavaScript ready
OTP Module
Send and verify codes
Webhooks
Status updates to your app

Authentication

Use the API credentials from your Developer API page. Protected endpoints accept credentials through headers.

HeaderRequiredDescription
X-API-USERNAMEYesYour account username.
X-API-KEYYesYour API key.
X-API-SECRETYesYour private API secret.

Endpoints

MethodEndpointNameDescriptionPermission
POST/api/sendSend SMSSingle, bulk, group and scheduled messages.send
GET/api/statusDelivery statusCheck one message by SMS ID or provider ID.reports
GET/api/balanceBalanceRead wallet and SMS unit balances.balance
POST/api/otp/sendSend OTPCreate and send a verification code.otp
POST/api/otp/verifyVerify OTPConfirm a verification code.otp
POST/api/delivery-callbackDelivery callbackProvider delivery updates receiver.callback
POST/api/webhook-testWebhook testSend a sample event to your webhook.webhook

Send SMS

Supports single, bulk, group and scheduled messages.

POST /api/send
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();
Required fields
mode, sender_id, phone or phones, message
Success response
{"success":true,"sms_id":"SMS-XXXX","status":"sent","charged":1}

OTP API

POST
Send OTP
/api/otp/send
{"phone":"2547XXXXXXX","purpose":"login","sender_id":"TextSMS"}
POST
Verify OTP
/api/otp/verify
{"phone":"2547XXXXXXX","purpose":"login","code":"123456"}

Delivery callbacks and webhooks

Provider callback

Give this URL to your SMS provider when delivery reports are available.

https://stk-push.top/api/delivery-callback
User webhook payload
{"sms_id":"SMS-XXXX","phone":"2547...","status":"delivered","reason":"Delivered","time":"2026-07-20 00:12:26"}

Live API Tester

Test your API directly from this documentation page. Your credentials stay inside your browser and are sent only to your own API endpoint.

Test before integration
Use your real API username, key and secret from your Developer API page. Start with a test phone number before sending real bulk messages.
API Username
API Key
API Secret
Test Type
Sender ID
Phone Number
OTP Code
Message
Response
Ready. Fill the form and run a test.

Security and limits

IP whitelist

Restrict API access to trusted servers.

Key permissions

Limit keys to sending, balance, reports or OTP.

Rate limits

Protect accounts from high-volume abuse.

Common responses

HTTPMeaningCommon fix
400Missing or invalid fields.Check request body.
401Invalid API credentials.Confirm username, key and secret.
403Blocked by permission, IP or account status.Review API security settings.
429Rate limit reached.Reduce request speed.
503Provider or setup unavailable.Try again or contact support.
Processing
Please wait a moment
Support