Sender IDs

Request and manage the sender name that appears on recipients' handsets.

A sender ID is the alphanumeric name (e.g. MYAPP) or shortcode that shows as the message sender on the recipient's phone. Every message you send, whether a single API send or a campaign, must reference an approved sender ID.

Approval required

A newly registered sender ID starts in pending approval status. You can only send with it once it reaches approved approval status and active status. Registration includes document uploads that an admin reviews before approving.

List sender IDs

GET/api/v1/sender-ids

Returns all sender IDs your team owns or has been granted access to.

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/sender-ids" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

200: OK

{
  "success": true,
  "data": [
    {
      "uuid": "sid-uuid",
      "sender_id": "MYAPP",
      "sender_type": "alphanumeric",
      "networks": ["safaricom", "airtel"],
      "approval_status": "approved",
      "status": "active"
    }
  ]
}

Register a sender ID

POST/api/v1/sender-idsmultipart/form-data

Submitted as multipart/form-data because supporting documents (a request letter per network, and your business registration) are uploaded alongside the fields.

Form fields

sender_idreq

string

The sender name (e.g. MYAPP) or shortcode number

sender_typereq

string

alphanumeric | shortcode

networksreq

JSON array

JSON-encoded list: ["safaricom","airtel","telkom","equitel"]

description

string

Brief description of how the sender ID will be used

request_letter_{network}

file

Request letter PDF per network, e.g. request_letter_safaricom

business_registration

file

Business registration certificate (shared across all networks)

curl

curl -X POST "$NEXT_PUBLIC_API_URL/api/v1/sender-ids" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F 'sender_id=MYAPP' \
  -F 'sender_type=alphanumeric' \
  -F 'networks=["safaricom","airtel"]' \
  -F 'description=Customer notifications for Acme Ltd' \
  -F 'request_letter_safaricom=@letter_safaricom.pdf' \
  -F 'business_registration=@reg_cert.pdf'

After submission

The sender ID is created in pending approval status. Poll the get endpoint below and wait for approval_status: "approved" and status: "active" before using it to send.

Get a sender ID

GET/api/v1/sender-ids/{uuid}

Fetch a single sender ID by UUID, including its current approval and active status.

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/sender-ids/sid-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Delete a sender ID

DELETE/api/v1/sender-ids/{uuid}

Removes a sender ID your team owns.

curl -X DELETE "https://timisha-solutions-api.salamu.co.ke/api/v1/sender-ids/sid-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Next steps

Once approved, use the sender ID UUID when sending a campaign or a single message via the messages endpoint.