Developer reference

JMSURF SMS API

Send one live SMS per request using your wallet balance. Create and revoke keys in your workspace.

Authentication

Use a key beginning with jms_live_ in the Authorization: Bearer header. Create keys under API keys in your tenant workspace. Keys are displayed only once. Store them on your server, never in browser code.

Send a message

POST /api/sms/send

curl -X POST https://sms.jmsurf.co.ke/api/sms/send \
  -H "Authorization: Bearer YOUR_JMSURF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"+254712345678","message":"Hello from JMSURF","reference":"8f6241c0-24df-4ce2-b39b-9ef85eab198f"}'

to is an international E.164 phone number. message allows up to 1,600 characters. reference is a UUID you generate for each new message.

Response and billing

A successful request returns HTTP 202 with id, status, segments and costKes. A message costs KES 0.70 per segment. An identical reference for the same account returns the original message without sending again. A definite carrier rejection refunds the wallet. An uncertain carrier result remains reserved for reconciliation.

Errors

HTTP 400 means invalid input, 401 means an invalid or revoked key, 402 means insufficient wallet credit, 422 means the carrier rejected the message, and 500 means the request needs support or reconciliation. Keep the original reference if you retry after a network error.