Sender IDs

Base path: /senders

By default your messages are sent from the shared sender ID WakaliLabs, with your company name automatically prefixed to the message body. To send under your own brand name, register a custom Sender ID.

List your Sender IDs

GET /senders

{
  "system": "WakaliLabs",
  "senders": [
    {
      "id": "...", "name": "MAMAMBOGA", "network": "safaricom",
      "status": "approved", "is_active": true, "is_default": true,
      "registration_fee": 1500.0, "fee_paid": true,
      "rejection_reason": null, "created_at": "2026-06-01T00:00:00Z"
    }
  ]
}

Request a Sender ID

POST /senders

{ "name": "MamaMboga", "purpose": "Order notifications", "network": "safaricom" }

• name — 2–11 alphanumeric characters (spaces are stripped, then upper-cased).
• network — one of safaricom, airtel, telkom, all. Each carries its own registration fee.

409 if you already have a request for that exact name + network.

Application flow

applied → documents_submitted → payment_pending → approved
                            ↘ rejected → re-apply

1. Submit documents — POST /senders/{sender_id}/documents, multipart/form-data with four required files: business_cert, kra_pin, auth_letter, request_letter. Download the master templates first from GET /senders/templates/{auth-letter|request-letter}/download.
2. Pay the registration fee — POST /senders/{sender_id}/pay, returns an authorization_url the same way wallet top-up does.
3. Wakali reviews the submission and approves or rejects it. On rejection, rejection_reason is set — fix and call POST /senders/{sender_id}/re-apply (no second fee, since it’s already paid) to resubmit documents.

Set default

PATCH /senders/{sender_id}/set-default — only works on an already-approved + active sender. Only one Sender ID can be default at a time; setting a new one clears the previous default.

Cancel a request

DELETE /senders/{sender_id} — cannot cancel a Sender ID that’s already approved and active.