Sozuri Developer Documentation

Subscription premium SMS lets you bill subscribers on a recurring schedule — daily, weekly or monthly — for content delivered to their phone. Customers opt in via your shortcode, and the carrier charges them automatically until they opt out.

POST https://sozuri.net/api/v1/premium

How the subscription flow works
Send a premium message: request
Send a premium message: response
Sample send-message request
Activate or deactivate a subscriber
Subscriber webhooks (activate, deactivate, consent, delivery)
Error responses

How the subscription flow works

A subscriber opts in by texting your keyword (e.g. JOIN) to your shortcode — or you call the activate endpoint on their behalf with explicit consent.
Sozuri pushes an activation webhook with the subscriber’s number and the keyword they used.
You send recurring premium content via the API. Each message triggers a charge.
Delivery and unsubscribe events stream to your webhook as they happen.

Subscription premium SMS requires an approved premium shortcode and a subscription billing arrangement with each carrier. Apply from your dashboard at Numbers › Apply for a shortcode — our team handles the carrier paperwork.

Send a premium message: request parameters

Required headers

POST /api/v1/premium HTTP/1.1
Host: sozuri.net
Authorization: Bearer Your_Project_API_KEY
Content-Type: application/json
Accept: application/json

Field	Required	Type	Description
project	Yes	String	The Sozuri project that owns the API key.
from	Yes	String	Your premium shortcode.
number	Yes	String	The subscriber’s phone in E.164. `0722-503-129` normalises to `254722503129`.
channel	Yes	String	Always `premium`.
type	Yes	String	Always `subscription` on this endpoint.
keyword	Yes	String	The keyword identifying the subscription service.
message	Yes	String	The premium content to send.
campaign	No	String	Optional label for reporting.
apiKey	—	String	Your project API key. Recommended: send as a `Bearer` token instead.

Send a premium message: response

Field	Type	Description
messageData.messages	Number	Total messages accepted.
recipients[].messageId	String	Unique Sozuri ID for this message.
recipients[].to	String	The recipient’s phone number.
recipients[].status	String	Acceptance status — not the final delivery status.
recipients[].statusCode	String	Numeric status — see status codes.
recipients[].messagePart	Number	SMS parts used.
recipients[].type	String	Always `subscription` here.

Sample request

POST /api/v1/premium HTTP/1.1
Host: sozuri.net
Authorization: Bearer LOx5JPdqf0lvf.......R9X9XDJ4PFxRqVrt9dx83cWiwfTQMF
Content-Type: application/json
Accept: application/json

{
    "project": "my project",
    "from": "23546",
    "number": "2547251642xx",
    "campaign": "Daily Quote",
    "channel": "premium",
    "message": "Today's quote: The best way out is always through. - Robert Frost.",
    "type": "subscription",
    "keyword": "Omoka"
}

Sample JSON response

{
    "messageData": { "messages": 1 },
    "recipients": [
        {
            "messageId": "MSGBLK6012A7E8B90A21611835368",
            "to": "2547251642xx",
            "status": "accepted",
            "statusCode": "11",
            "messagePart": 1,
            "type": "subscription"
        }
    ]
}

Activate or deactivate a subscriber

You can register or remove subscribers yourself — for example, when a customer opts in from a web form rather than via SMS. The request is the same shape; only the type differs.

Activate

curl -X POST https://sozuri.net/api/v1/premium \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer Your_Project_API_KEY' \
    -d '{
        "project": "my project",
        "shortcode": "25145",
        "keyword": "Omoka",
        "number": "2547251642xx",
        "network": "safaricom",
        "type": "activate"
    }'

Deactivate

curl -X POST https://sozuri.net/api/v1/premium \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer Your_Project_API_KEY' \
    -d '{
        "project": "my project",
        "shortcode": "25145",
        "keyword": "Omoka",
        "number": "2547251642xx",
        "network": "safaricom",
        "type": "deactivate"
    }'

Carriers require explicit user consent before you activate a subscriber on their behalf. Keep proof of consent (form submission, voice call recording, etc.) — this is what carriers audit when disputes arise.

Subscriber webhooks

You’ll receive four kinds of asynchronous webhooks. Configure the receiving URL from Manage API › Callback URLs.

1. Activation

Fires when a subscriber opts in — either by texting your keyword to your shortcode, or after a successful activate API call.

{
    "project": "yourproject_name",
    "shortcode": "25145",
    "keyword": "JOIN",
    "number": "2547251xxxxx",
    "network": "safaricom",
    "type": "activation",
    "status": "success",
    "timestamp": "1603713484"
}

2. Deactivation

Fires when a subscriber opts out — via your STOP keyword, USSD menu or carrier dashboard.

{
    "project": "yourproject_name",
    "shortcode": "25145",
    "keyword": "JOIN",
    "number": "2547251xxxxx",
    "network": "safaricom",
    "type": "deactivation",
    "status": "success",
    "timestamp": "1603713484"
}

Fires after you call the activate API. Status is success if the carrier accepted the activation, or failure if the subscriber rejected the consent prompt.

{
    "project": "yourproject_name",
    "shortcode": "25145",
    "keyword": "JOIN",
    "number": "2547251xxxxx",
    "network": "safaricom",
    "type": "consent",
    "status": "failure",
    "timestamp": "1603713484"
}

4. Delivery status

Fires for each premium message you sent — one event per state change.

{
    "project": "yourproject_name",
    "shortcode": "25145",
    "keyword": "JOIN",
    "number": "2547251xxxxx",
    "network": "safaricom",
    "type": "premiumDelivery",
    "status": "success",
    "timestamp": "1603713484"
}

Optional callback authentication

Register an Auth Key on your callback URL to verify webhooks are genuinely from Sozuri — we’ll include the key in every callback body.

Error responses

Subscription premium SMS uses the SDP error envelope: { "status": "error", "description": "…" }. Auth errors (Unknown project.) follow the SMS envelope and are documented on the Authentication page.

Condition	HTTP	Response body
Trying to activate a subscriber who is already active on this premium service.	400	`{ "status": "error", "description": "Subscriber already Exists" }`
Trying to deactivate a number that was never subscribed to this premium service.	400	`{ "status": "error", "description": "Unknown Subscriber" }`
Trying to deactivate a subscriber who is already inactive.	400	`{ "status": "error", "description": "Subscriber is already Inactive" }`
Keyword doesn’t match an active premium service on this project.	400	`{ "status": "error", "description": "Unknown, Expired, or Inactive Premium Service" }`
Destination phone number is malformed or not in supported E.164 format.	400	`{ "status": "error", "description": "Unsupported Number" }`

For status code reference see Status codes & response envelopes. For asynchronous delivery callbacks see Delivery webhook statuses.

Daily content (quotes, devotionals, jokes)

Subscriber pays a daily fee to receive one short message a day — the original mobile content business model, still huge.

“The best way out is always through.” — Robert Frost. Send STOP to unsubscribe. 07:00

Health & wellness tips

Weekly maternal-health, HIV-adherence or chronic-care reminders — works on every phone, no data needed.

AfyaTip: Week 24. Your baby is now about 30 cm long. Visit the clinic for your second trimester check-up this week. 08:00

Agronomy & market prices

Daily commodity prices for farmers, weather alerts, planting tips — high-value content for rural subscribers.

Today’s Nairobi prices:
Maize KES 4,200 / 90kg bag
Beans KES 9,800 / 90kg
Milk KES 55 / litre

Rain expected in Eldoret tomorrow. 06:00

Sports & betting tips

Tipsters and sports networks monetise daily picks via opt-in subscriptions.

Launch a recurring SMS service.

We’ll set up the shortcode, register your keyword and handle billing reconciliation with the carrier.

Apply for a shortcode See on-demand model

Subscription premium SMS

How the subscription flow works

Send a premium message: request parameters

Required headers

Send a premium message: response

Sample request

Sample JSON response

Activate or deactivate a subscriber

Activate

Deactivate

Subscriber webhooks

1. Activation

2. Deactivation

3. Consent

4. Delivery status

Optional callback authentication

Error responses

Use cases

Daily content (quotes, devotionals, jokes)

Health & wellness tips

Agronomy & market prices

Sports & betting tips

Launch a recurring SMS service.