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.

# Paste your token once (it starts with mbs_):
export MOBILESASA_TOKEN="mbs_your_token_here"

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:

# Paste your token once (it starts with mbs_):
export MOBILESASA_TOKEN="mbs_your_token_here"

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.

# Paste your token once (it starts with mbs_):
export MOBILESASA_TOKEN="mbs_your_token_here"

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.

# Paste your token once (it starts with mbs_):
export MOBILESASA_TOKEN="mbs_your_token_here"

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.

Short-term rentals

A platform-shortcode keyword can also be rented for a fixed term rather than month-to-month: pass rental_days (1–90) and the fee is a pro-rata share of the monthly rate (monthly × days ÷ 30, rounded up, VAT inclusive), charged upfront from your wallet. The keyword expires at the end of the term with no renewal and no further charges — ideal for a campaign week or a pilot.

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:

# Paste your token once (it starts with mbs_):
export MOBILESASA_TOKEN="mbs_your_token_here"

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"
  }
}

Releasing a keyword

DELETE/api/v1/keywords/{uuid}

Pausing with is_active: false keeps the word reserved and a paused monthly keyword can still be renewed and charged. To stop paying for a keyword, release it. Needs team:keywords:manage.

What happens

Field	Type	Required	Description
Inbound	stops	No	Texts starting with the keyword or an alias no longer reach you, at once.
Billing	stops	No	The keyword is never renewed or charged again. The current term is not refunded.
The word	freed	No	The keyword and its aliases can be reserved again on that shortcode, by you or anyone else.

Close the survey first

A keyword that still starts an active survey is not released: the call returns 409. Close or pause the survey, then release the keyword. A release cannot be undone; to use the word again, apply for it as a new keyword.

Draft, pending and rejected keywords can be released too, which simply withdraws them. Another team's keyword returns 404.

# Paste your token once (it starts with mbs_):
export MOBILESASA_TOKEN="mbs_your_token_here"

curl -X DELETE "https://api.mobilesasa.com/api/v1/keywords/8c11d2ab-…" \
  -H "Authorization: Bearer $MOBILESASA_TOKEN"

Response: 200

{ "success": true }

Keyword → survey

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