Sender IDs

A sender ID is the name or number that appears as the originator of your SMS. Registering a branded alphanumeric sender ID (for example AFRIROUTE) significantly improves deliverability and trust compared to shared numbers. This page covers registering, listing, and managing sender IDs.

🏷️ Sender ID Types

Type	Example	Notes
Alphanumeric	AFRIROUTE	3-11 characters, letters/digits, one-way only (recipients cannot reply)
Numeric (long code)	+251700000000	Supports two-way messaging
Short code	8000	Operator-issued, high throughput, region-specific

Many African operators require alphanumeric sender IDs to be pre-registered and approved. Registration can take 1-7 business days depending on the country.

📡 Endpoints

Method	Path	Purpose
GET	/v1/sms/sender-ids	List your sender IDs and their status
POST	/v1/sms/sender-ids	Register a new sender ID for approval
DELETE	/v1/sms/sender-ids/{id}	Remove a sender ID

Base URL: https://api.afriroute.ai

📋 List Sender IDs

curl https://api.afriroute.ai/api/v1/sms/sender-ids \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY"

const res = await fetch('https://api.afriroute.ai/api/v1/sms/sender-ids', {
  headers: { 'Authorization': 'Bearer $AFRIROUTE_API_KEY' }
});
const { sender_ids } = await res.json();

import requests

res = requests.get(
    'https://api.afriroute.ai/api/v1/sms/sender-ids',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
)
print(res.json()['sender_ids'])

Response

{
  "sender_ids": [
    {
      "id": "sid_abc123",
      "name": "AFRIROUTE",
      "type": "alphanumeric",
      "status": "approved",
      "countries": ["ET", "KE", "NG"],
      "created_at": "2026-04-10T09:00:00Z"
    }
  ]
}

➕ Register a Sender ID

POST /v1/sms/sender-ids

Field	Type	Required	Description
name	string	Yes	The sender ID (3-11 alphanumeric chars)
type	string	Yes	alphanumeric, numeric, or short_code
countries	array	Yes	ISO 3166-1 alpha-2 codes where it will be used
use_case	string	Yes	Description of how it will be used (required by operators)

curl -X POST https://api.afriroute.ai/api/v1/sms/sender-ids \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MYBRAND",
    "type": "alphanumeric",
    "countries": ["ET", "KE"],
    "use_case": "Transactional OTP and order notifications"
  }'

Response

{
  "id": "sid_def456",
  "name": "MYBRAND",
  "type": "alphanumeric",
  "status": "pending",
  "countries": ["ET", "KE"],
  "created_at": "2026-05-28T10:30:00Z"
}

🟢 Sender ID Statuses

Status	Meaning
pending	Submitted, awaiting operator approval
approved	Live and ready to use as a from value
rejected	Declined; review the rejection_reason and resubmit

❌ Delete a Sender ID

curl -X DELETE https://api.afriroute.ai/api/v1/sms/sender-ids/sid_def456 \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY"

Returns 204 No Content on success.

💡 Best Practices

• Register early — approval can take several business days per country.
• Keep names recognisable and consistent with your brand for higher trust.
• Use alphanumeric IDs for transactional traffic to maximise deliverability.
• Choose numeric/long codes when recipients need to reply.
• Provide a clear use_case — vague descriptions are commonly rejected.
• Avoid generic words like INFO or SMS that operators frequently reject.

⚠️ Error Handling

HTTP	Code	Resolution
400	INVALID_SENDER_ID	Use 3-11 valid alphanumeric characters
409	SENDER_ID_EXISTS	This sender ID is already registered
422	SENDER_ID_REJECTED	Operator declined; revise and resubmit

See Error Codes for the full list.

📚 Related Resources

• Send SMS
• Bulk SMS
• Delivery Reports
• SMS API Overview

---

Last Updated: May 2026 · Need help? Contact Support →