Keywords

A keyword is the first word of an inbound text that routes it to you — TEXT 'BALANCE to 40404'. Reserve keywords on your own shortcode or on the shared platform shortcode, and point each at an auto-reply, your webhook, or a survey.

Endpoints live under /api/v1/ with a scoped mbs_ token or JWT. Keywords go through a short review (draft → submitted → approved) before they start matching traffic.

Which shortcodes can I use?

GET/api/v1/keywords/shortcodes

Lists the shortcodes available to your team: your own approved shortcodes plus the shared platform shortcode anyone can reserve keywords on.

curl "https://api.mobilesasa.com/api/v1/keywords/shortcodes" \
  -H "Authorization: Bearer $MOBILESASA_TOKEN"

Check availability

GET/api/v1/keywords/available

Keywords are unique per shortcode — check before applying:

curl "https://api.mobilesasa.com/api/v1/keywords/available?shortcode=40404" \
  -H "Authorization: Bearer $MOBILESASA_TOKEN"

Create a keyword application

POST/api/v1/keywords

Parameters

Field	Type	Required	Description
shortcode_uuid	uuid	Yes	The shortcode to reserve the keyword on — from the shortcodes listing above.
keyword	string	Yes	The word customers text first, matched case-insensitively (e.g. BALANCE).
aliases	string[]	No	Alternative spellings that match the same keyword (e.g. ["BAL", "BALANCES"]).
auto_reply	string	No	Instant SMS reply sent to the customer on every match — before/instead of your own reply.
callback_url	string	No	HTTPS URL to receive each matched text — the payload is documented under inbound webhooks.

curl -X POST https://api.mobilesasa.com/api/v1/keywords \
  -H "Authorization: Bearer $MOBILESASA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shortcode_uuid": "3f0c8d12-…",
    "keyword": "BALANCE",
    "aliases": [
      "BAL"
    ],
    "auto_reply": "Checking your balance — you'll get a reply shortly.",
    "callback_url": "https://example.com/webhooks/keywords"
  }'

Submit for review

POST/api/v1/keywords/{uuid}/submit

A keyword is created as a draft so you can finish configuring it; submitting moves it to pending for review.

curl -X POST https://api.mobilesasa.com/api/v1/keywords/8c11d2ab-…/submit \
  -H "Authorization: Bearer $MOBILESASA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

approval_status values

Field	Type	Required	Description
draft	initial	No	Editable; not yet in review and not matching traffic.
pending	in review	No	Submitted and awaiting review.
approved	final	No	Live — inbound texts starting with the keyword (or an alias) route to you.
rejected	final	No	Declined; rejection_reason carries the why. Fix and re-submit.

Shared-shortcode keywords carry a reservation fee

Reserving a keyword on the shared platform shortcode deducts a reservation fee from your KES wallet on approval — keep it funded while the keyword is pending. Keywords on your own shortcode are free.

Track and update

GET/api/v1/keywords

GET/api/v1/keywords/{uuid}

PATCH/api/v1/keywords/{uuid}

The PATCH endpoint updates the runtime configuration — auto-reply, callback URL, or an is_active kill-switch — without another review round:

curl -X PATCH https://api.mobilesasa.com/api/v1/keywords/8c11d2ab-… \
  -H "Authorization: Bearer $MOBILESASA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://example.com/webhooks/keywords-v2",
    "is_active": true
  }'

Keyword resource

{
  "success": true,
  "data": {
    "uuid": "8c11d2ab-…",
    "shortcode": "40404",
    "keyword": "BALANCE",
    "aliases": ["BAL"],
    "approval_status": "approved",
    "is_active": true,
    "auto_reply": "Checking your balance — you'll get a reply shortly.",
    "callback_url": "https://example.com/webhooks/keywords",
    "total_inbound": 1284,
    "created_at": "2026-07-01T09:00:00Z"
  }
}

Keyword → survey

Attach a survey to a keyword and every text matching it starts a structured survey session instead of hitting your webhook.