SMS API for Developers

How an SMS API works

1. Your application makes an HTTP request to the send endpoint with the recipient's number, the message text, your sender ID and your credentials.
2. The gateway authenticates and validates — key and IP whitelist, number format, blacklist, credit balance — and returns a response immediately, including a message ID.
3. The gateway routes and submits the message to the recipient's network over its carrier connection.
4. The network returns a delivery report, stored against the message ID. You poll it, receive it on a callback URL, or read it in the dashboard.

The Ontech BulkSMS API at a glance

All endpoints are on https://bulksms.ontech.co.zm, return JSON with a numeric status (100 success, 101 insufficient credit, 102 invalid user, 103 validation error, 104 rate limit), and accept the same authentication. The complete parameter reference is on the API documentation page and in the CloudService API guide (PDF).

Authentication

Generate credentials under API Keys → Generate Key in your dashboard. Each key has an Access ID and a Secret Key; pass either as api_key. Keys only work from the IP addresses you whitelist for them, so add your server's address before going live — a request from elsewhere returns 102 Invalid User. Username and password (your login email and password) are accepted as an alternative, but a key is the right choice for anything deployed.

Send a message

# HTTP API — GET or POST, query parameters
curl "https://bulksms.ontech.co.zm/smsservice/httpapi?\
api_key=YOUR_ACCESS_ID&phone=260970000000&sender_id=YOURBRAND&msg=Hello%20from%20the%20API"
# → {"status": 100, "message": "Success", "message_id": "…"}

# JSON API — many recipients in one request
curl -X POST https://bulksms.ontech.co.zm/smsservice/jsonapi \
  -H "Content-Type: application/json" \
  -d '{"auth": {"api_key": "YOUR_ACCESS_ID", "sender_id": "YOURBRAND"},
       "messages": [{"phone": "260970000000", "message": "Hello Mutale"},
                    {"phone": "260960000000", "message": "Hello Chanda"}]}'
# → {"status": 100, "message": "Success", "sent": 2}

Numbers are Zambian MSISDNs — 260 followed by nine digits; local forms such as 0970000000 are normalised. Non-Zambian numbers are rejected with a 103.

Check delivery

curl "https://bulksms.ontech.co.zm/smsservice/status?api_key=YOUR_ACCESS_ID&message_id=MESSAGE_ID"
# → {"status": 100, "message": "Success", "message_id": "…", "delivery_status": "delivered"}

delivery_status is one of delivered, failed, rejected, queued (not yet submitted), submitted (carrier accepted, no final report yet) or unknown. Rather than polling, register a callback URL under Webhooks and delivery updates are posted to you with retries. The delivery reports guide explains each state.

Limits and safeguards

• 60 requests per minute per account across the API. Batch through the JSON API's messages array; for sustained volume use SMPP.
• Duplicate guard. An identical message to the same number from the same account within three minutes is suppressed and reported as "Duplicate suppressed", protecting you from double-sends on retries.
• Blacklist. Numbers on your opt-out list are skipped and reported, never sent.
• Sender ID. Only sender IDs approved on your account are accepted; an unapproved one returns a 103.
• Credits. A send that would exceed your balance returns 101 Insufficient Credit; top up from the dashboard, the app, or the /topup endpoint.
• Logging. Every request is recorded against your account with its outcome, visible under Integrations.

How businesses integrate SMS into an application

The pattern is the same whether it is a loan system, a school platform or an online shop:

1. Create an account, generate an API key, whitelist the server's IP, and request a sender ID.
2. Identify the events that should produce a message — a payment, a booking, a due date, a code request — and write a template for each.
3. At each event, build the message and call the send endpoint; store the returned message ID with the record it relates to.
4. Register a callback URL (or poll status for the messages that matter) and store the delivery state alongside the message ID.
5. Watch your balance (/balance) and set a low-balance alert in the dashboard so notifications never stop for want of credits.

Worked examples for the common cases: transactional notifications, one-time passwords and receiving replies. For the protocol-level alternative, see SMPP.

Developer resources