Developers · Beam SMS API

Beam SMS API reference

Beam SMS's programmable API lets you send SMS messages directly from your application. Create a message object with a single request and Beam returns the created message with each call.

Get your API token Base URL: https://bulksms.beamnetworks.co.ke/api/v3

Authentication

Every request must be authenticated with your API token as a Bearer token, and must accept JSON. Send these headers with each call:

Header	Required	Description
Authorization	Yes	Your API token with the authentication type set as Bearer (e.g. `Authorization: Bearer {api_token}`).
Accept	Yes	Set to `application/json`.

Send an SMS

POSThttps://bulksms.beamnetworks.co.ke/api/v3/sms/send

Programmatically send SMS messages from your application. Send to a single number, or to multiple numbers by separating them with a comma.

Parameters

Parameter	Required	Type	Description
recipient	Yes	string	Number to send the message to. Use a comma (,) to send to multiple numbers, e.g. 254781000403,254707711847
sender_id	Yes	string	The sender of the message — a telephone number (with country code) or an alphanumeric string (max 11 characters).
type	Yes	string	The message type. For a text message, use plain.
message	Yes	string	The body of the SMS message.
schedule_time	No	datetime	Scheduled date and time in RFC3339 format (Y-m-d H:i).
dlt_template_id	No	string	The ID of your registered DLT content template.

Examples

Single number

curl -X POST https://bulksms.beamnetworks.co.ke/api/v3/sms/send \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "recipient": "254700000000",
    "sender_id": "YourBrand",
    "type": "plain",
    "message": "This is a test message"
  }'

Multiple numbers, scheduled

curl -X POST https://bulksms.beamnetworks.co.ke/api/v3/sms/send \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "recipient": "254781000403,254707711847",
    "sender_id": "YourBrand",
    "type": "plain",
    "message": "This is a test message",
    "schedule_time": "2026-12-20 07:00"
  }'

Send a campaign using a contact list

POSThttps://bulksms.beamnetworks.co.ke/api/v3/sms/campaign

Send a campaign to one or more saved contact lists instead of raw numbers. Separate multiple contact list IDs with a comma.

Parameters

Parameter	Required	Type	Description
contact_list_id	Yes	string	Contact list to send to. Use a comma (,) to send to multiple lists.
sender_id	Yes	string	The sender of the message — a number (with country code) or an alphanumeric string (max 11 characters).
type	Yes	string	The message type. For a text message, use plain.
message	Yes	string	The body of the SMS message.
schedule_time	No	datetime	Scheduled date and time in RFC3339 format (Y-m-d H:i).
dlt_template_id	No	string	The ID of your registered DLT content template.

Examples

Single contact list

curl -X POST https://bulksms.beamnetworks.co.ke/api/v3/sms/campaign \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "contact_list_id": "6415907d0d37a",
    "sender_id": "YourBrand",
    "type": "plain",
    "message": "This is a test message"
  }'

Multiple contact lists, scheduled

curl -X POST https://bulksms.beamnetworks.co.ke/api/v3/sms/campaign \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "contact_list_id": "6415907d0d37a,6415907d0d7a6",
    "sender_id": "YourBrand",
    "type": "plain",
    "message": "This is a test message",
    "schedule_time": "2026-12-20 07:00"
  }'

View an SMS

GEThttps://bulksms.beamnetworks.co.ke/api/v3/sms/{uid}

Retrieve an existing inbound or outbound message. Supply the unique messageuid returned when the message was created.

Request

curl -X GET https://bulksms.beamnetworks.co.ke/api/v3/sms/606812e63f78b \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

View all messages

GEThttps://bulksms.beamnetworks.co.ke/api/v3/sms

Retrieve all of your messages. Results are returned with pagination.

Request

curl -X GET https://bulksms.beamnetworks.co.ke/api/v3/sms \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Responses

A successful request returns a JSON object with a success status. A failed request returns an error status with a human-readable message.

Success

200 OK

{
  "status": "success",
  "data": "sms reports with all details"
}

Error

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