API Documentation

Developer documentation v3 · 2026

Start here

MobiWave Innovations API

The API uses a versioned base URL and JSON responses. All requests should use HTTPS and include your bearer token in the Authorization header.

Base URL

https://sms.mobiwave.co.ke/api/v3

Developer portal

Security

Authentication

MobiWave uses bearer tokens. Generate a token in the Developer section of the SMS Platform and keep it on your server. Never commit tokens to source control or expose them in browser code.

Bearer token

Send your token with every request.

JSON headers

Use application/json for request and response handling.

Protect secrets

Store tokens in environment variables or a secret manager.

cURL

curl https://sms.mobiwave.co.ke/api/v3/balance \
  -H "Authorization: Bearer {api_token}" \
  -H "Accept: application/json"

Conventions

Responses

Successful and failed requests return a consistent JSON envelope.

cURL

{
  "status": "success",
  "data": { "uid": "resource_uid" }
}

cURL

{
  "status": "error",
  "message": "A human-readable description of the error."
}

Contact management

Contacts API

Programmatically create, read, update, delete, and list contacts.

POST/contacts/{group_id}/store

Store a contact

Creates a contact in a contact group.

Parameter	Type	Required	Description
group_id	string	Yes	Contact group UID
phone	string	Yes	Phone number in international format
first_name	string	No	Contact first name
last_name	string	No	Contact last name

cURL

curl -X POST https://sms.mobiwave.co.ke/api/v3/contacts/{group_id}/store \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"phone":"254700000000","first_name":"Amina"}'

POST/contacts/{group_id}/search/{uid}

View a contact

Retrieves an existing contact by its UID and group UID.

PATCH/contacts/{group_id}/update/{uid}

Update a contact

Updates an existing contact.

Parameter	Type	Required	Description
group_id	string	Yes	Contact group UID
uid	string	Yes	Contact UID
phone	string	Yes	Updated phone number
first_name	string	No	Updated first name
last_name	string	No	Updated last name

DELETE/contacts/{group_id}/delete/{uid}

Delete a contact

Removes an existing contact from a group.

POST/contacts/{group_id}/all

List contacts in a group

Returns paginated contacts belonging to a group.

Contact management

Contact groups API

Organize contacts into reusable groups for targeted campaigns.

POST/contacts

Create a contact group

Creates a new group for organizing contacts.

Parameter	Type	Required	Description
name	string	Yes	Name of the group

cURL

curl -X POST https://sms.mobiwave.co.ke/api/v3/contacts \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Customers"}'

POST/contacts/{group_id}/show

View a group

Retrieves a group by its UID.

PATCH/contacts/{group_id}

Update a group

Updates an existing group name.

Parameter	Type	Required	Description
group_id	string	Yes	Contact group UID
name	string	Yes	New group name

DELETE/contacts/{group_id}

Delete a group

Deletes an existing contact group.

GET/contacts

List contact groups

Returns paginated contact groups for the account.

Messaging

SMS API

Send outbound SMS, schedule messages, run campaigns, and retrieve delivery reports.

POST/sms/send

Send an outbound SMS

Sends a message to one or more recipients. Separate multiple recipients with commas.

Parameter	Type	Required	Description
recipient	string	Yes	One or more phone numbers
sender_id	string	Yes	Number or alphanumeric sender ID, max 11 characters
type	string	Yes	Use plain for text SMS
message	string	Yes	Message body
schedule_time	datetime	No	Scheduled send time
dlt_template_id	string	No	Registered content template ID

cURL

curl -X POST https://sms.mobiwave.co.ke/api/v3/sms/send \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"recipient":"254700000000","sender_id":"MobiWave","type":"plain","message":"Your code is 123456"}'

POST/sms/campaign

Send a campaign

Sends a message to one or more contact lists.

Parameter	Type	Required	Description
contact_list_id	string	Yes	One or more contact list UIDs
sender_id	string	Yes	Number or alphanumeric sender ID
type	string	Yes	Use plain for text SMS
message	string	Yes	Message body
schedule_time	datetime	No	Scheduled send time

GET/sms/{uid}

View a message

Retrieves an inbound or outbound message by UID.

GET/sms

List messages

Returns paginated SMS reports for the account.

Messaging

WhatsApp API

Send WhatsApp messages through the messaging endpoint using the whatsapp message type.

POST/sms/send

Send a WhatsApp message

Uses the messaging endpoint with type set to whatsapp.

Parameter	Type	Required	Description
recipient	string	Yes	WhatsApp recipient number
sender_id	string	Yes	Approved WhatsApp sender
type	string	Yes	Use whatsapp
message	string	Yes	Message body

cURL

curl -X POST https://sms.mobiwave.co.ke/api/v3/sms/send \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  -d '{"recipient":"254700000000","sender_id":"MobiWave","type":"whatsapp","message":"Hello from MobiWave"}'

GET/sms/{uid}

View a WhatsApp message

Retrieves a WhatsApp message report by UID.

GET/sms

List WhatsApp messages

Returns paginated messaging reports.

Account

Profile API

Retrieve authenticated profile information and available SMS units.

GET/me

View profile

Retrieves the authenticated account profile.

GET/balance

View SMS balance

Retrieves available SMS units.

Need help integrating?

Talk to the MobiWave team.

Get implementation guidance for SMS campaigns, WhatsApp messaging, contact migration, and production onboarding.

Contact support