DreamGuys SMS

API Documentation

Integrate Bulk SMS Portal into your application using our REST API.

Base URL

All requests are versioned:

https://dev.sms.dreamguys.africa/api/v1

Authentication

Every endpoint except the M-Pesa and SMS provider callbacks requires a Bearer token. Exchange your API key and secret for one:

POST /api/v1/auth/token

Returns a Bearer token (valid 24 hours). Send it as Authorization: Bearer TOKEN on every request.

curl -X POST https://dev.sms.dreamguys.africa/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"api_key":"KEY","api_secret":"SECRET"}'

Partner Accounts (Embedded SMS)

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.

POST /api/v1/customers/register

Requires the partner's Bearer token.

FieldTypeRequiredDescription
namestringrequiredCustomer/contact name
emailstringrequiredUnique account email
phonestringrequiredLocal (0712345678) or international digits
country_codestringoptionalDial code used for local numbers (default 254)
business_namestringoptionalBusiness name shown on the account
regionstringoptionalTwo-letter region code (default KE)
currencystringoptionalBilling currency (default KES)
passwordstringoptionalAccount password; generated if omitted
curl -X POST https://dev.sms.dreamguys.africa/api/v1/customers/register \
-H "Authorization: Bearer PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Acme ISP","email":"billing@acme.test","phone":"0712345678","business_name":"Acme Networks"}'

Response (201)

{"success":true,"message":"Customer registered successfully.","data":{"customer_id":"...","user_id":"...","account_number":"AB12C","api_key":"...","api_secret":"...","token":"1|...","token_type":"Bearer","expires_at":"...","balance":0,"currency":"KES","unit_rate":1,"sender_id":"MySender","sms_ready":true}}

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.

SMS Endpoints

All require Bearer token in Authorization header.

POST /api/v1/sms/send

Send to a single phone number.

FieldTypeRequiredDescription
sender_idstringrequiredRegistered sender ID
phonestringrequiredRecipient (e.g. 254712345678)
messagestringrequiredSMS content (max 1600 chars)
curl -X POST https://dev.sms.dreamguys.africa/api/v1/sms/send \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"sender_id":"MySender","phone":"254712345678","message":"Hello"}'

POST /api/v1/sms/send-bulk

Send to multiple numbers in one request.

curl -X POST https://dev.sms.dreamguys.africa/api/v1/sms/send-bulk \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"sender_id":"MySender","phones":["254712345678","254723456789"],"message":"Hello"}'

POST /api/v1/sms/send-group

Send to a contact group by its UUID.

FieldTypeRequiredDescription
sender_idstringrequiredRegistered sender ID
group_idUUIDrequiredContact group UUID
messagestringrequiredSMS content (max 1600 chars)
curl -X POST https://dev.sms.dreamguys.africa/api/v1/sms/send-group \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"sender_id":"MySender","group_id":"019f8b3e-...","message":"Hello Group"}'

GET /api/v1/balance

Check your SMS balance and the wallet account number used for payments.

curl https://dev.sms.dreamguys.africa/api/v1/balance \
-H "Authorization: Bearer TOKEN"
{"success":true,"data":{"account_number":"AB12C","units_balance":167,"currency":"KES","unit_rate":1,"value":167,"low_balance_threshold":100,"is_low":false}}

POST /api/v1/wallet/topup

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.

FieldTypeRequiredDescription
amountnumberrequiredAmount to charge (minimum 1)
phonestringrequiredM-Pesa number receiving the prompt
country_codestringoptionalDial code used for local numbers (default 254)
curl -X POST https://dev.sms.dreamguys.africa/api/v1/wallet/topup \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"amount":50,"phone":"0712345678"}'
{"success":true,"message":"M-Pesa prompt sent. Awaiting customer confirmation.","data":{"transaction_id":"...","reference":"...","status":"pending","amount":50,"currency":"KES","units_expected":167,"units_credited":0,"phone":"254712345678","receipt":null,"failure_reason":null,"balance":0,"created_at":"...","processed_at":null}}

GET /api/v1/wallet/topup/{transaction_id}

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.

curl https://dev.sms.dreamguys.africa/api/v1/wallet/topup/TRANSACTION_ID \
-H "Authorization: Bearer TOKEN"

GET /api/v1/groups

List your contact groups with contact counts.

curl https://dev.sms.dreamguys.africa/api/v1/groups \
-H "Authorization: Bearer TOKEN"

Rate Limits & Errors

CodeMeaning
200Success
201Customer registered
400Bad request
401Invalid credentials
402Low balance
404Resource not found
422Validation failed or payment rejected
429Too many requests

For API support, contact developers@dreamguys.africa.