Integrate Bulk SMS Portal into your application using our REST API.
All requests are versioned:
Every endpoint except the M-Pesa and SMS provider callbacks requires a Bearer token. Exchange your API key and secret for one:
Returns a Bearer token (valid 24 hours). Send it as Authorization: Bearer TOKEN on every request.
Register an SMS account from inside a partner application, such as an ISP billing system. The response contains the wallet account number and credentials, so SMS and top-ups can be used immediately without leaving the application. If the calling partner is a reseller, the new account is attached to them.
Requires the partner's Bearer token.
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | required | Customer/contact name |
| string | required | Unique account email | |
| phone | string | required | Local (0712345678) or international digits |
| country_code | string | optional | Dial code used for local numbers (default 254) |
| business_name | string | optional | Business name shown on the account |
| region | string | optional | Two-letter region code (default KE) |
| currency | string | optional | Billing currency (default KES) |
| password | string | optional | Account password; generated if omitted |
Response (201)
Store the returned credentials. Use the Bearer token (or exchange the API key/secret later) to send SMS, read the balance, and start top-ups. account_number is the wallet reference used for M-Pesa payments. If sms_ready is false, the account has no usable sender ID yet; the partner needs an approved sender before SMS can be sent.
All require Bearer token in Authorization header.
Send to a single phone number.
| Field | Type | Required | Description |
|---|---|---|---|
| sender_id | string | required | Registered sender ID |
| phone | string | required | Recipient (e.g. 254712345678) |
| message | string | required | SMS content (max 1600 chars) |
Send to multiple numbers in one request.
Send to a contact group by its UUID.
| Field | Type | Required | Description |
|---|---|---|---|
| sender_id | string | required | Registered sender ID |
| group_id | UUID | required | Contact group UUID |
| message | string | required | SMS content (max 1600 chars) |
Check your SMS balance and the wallet account number used for payments.
Send an M-Pesa STK prompt to top up the wallet without leaving your application. The amount is converted to SMS units at the current unit rate.
| Field | Type | Required | Description |
|---|---|---|---|
| amount | number | required | Amount to charge (minimum 1) |
| phone | string | required | M-Pesa number receiving the prompt |
| country_code | string | optional | Dial code used for local numbers (default 254) |
Poll the transaction returned by the top-up call. The wallet is credited as soon as M-Pesa confirms, even if the callback is delayed.
List your contact groups with contact counts.
| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Customer registered |
| 400 | Bad request |
| 401 | Invalid credentials |
| 402 | Low balance |
| 404 | Resource not found |
| 422 | Validation failed or payment rejected |
| 429 | Too many requests |
For API support, contact developers@dreamguys.africa.