API Reference

Complete reference documentation for all AfriRoute APIs. Each API provides RESTful endpoints with JSON payloads for seamless integration.

🌐 Base URLs

Environment	URL
Production	`https://api.afriroute.ai`
Sandbox	`https://sandbox.api.afriroute.ai`

🔑 Authentication

All API requests require authentication via one of these methods:

API Key (Recommended)

-H "Authorization: Bearer $AFRIROUTE_API_KEY"

JWT Token

-H "Authorization: Bearer your_jwt_token"

Learn more about authentication →

📡 Available APIs

1. SMS API

Send and receive SMS messages across Africa.

Send SMS: POST /v1/sms/send
Get Status: GET /v1/sms/{message_id}
Send Bulk SMS: POST /v1/sms/bulk
Get Balance: GET /v1/sms/balance

View SMS API Documentation →

2. WhatsApp API

Send rich media messages via WhatsApp Business API.

Send Message: POST /v1/whatsapp/send
Send Template: POST /v1/whatsapp/template
Upload Media: POST /v1/whatsapp/media
Get Message Status: GET /v1/whatsapp/{message_id}

View WhatsApp API Documentation →

3. Email API

Send transactional and marketing emails.

Send Email: POST /v1/email/send
Send Bulk Email: POST /v1/email/bulk
Get Status: GET /v1/email/{message_id}
Manage Templates: POST /v1/email/templates

View Email API Documentation →

4. Voice API

Make and receive voice calls programmatically.

Make Call: POST /v1/voice/call
Get Call Status: GET /v1/voice/{call_id}
Hangup Call: POST /v1/voice/{call_id}/hangup
Play Audio: POST /v1/voice/{call_id}/play

View Voice API Documentation →

5. USSD API

Build interactive USSD applications.

Initiate Session: POST /v1/ussd/initiate
Handle Response: POST /v1/ussd/callback
End Session: POST /v1/ussd/{session_id}/end

View USSD API Documentation →

6. Payments API

Accept mobile money payments across Africa.

Initiate Payment: POST /v1/payments/charge
Check Status: GET /v1/payments/{transaction_id}
Refund: POST /v1/payments/{transaction_id}/refund
Payment Methods: GET /v1/payments/methods

View Payments API Documentation →

7. Webhooks

Receive real-time notifications for events.

Configure Webhook: POST /v1/webhooks
List Webhooks: GET /v1/webhooks
Delete Webhook: DELETE /v1/webhooks/{webhook_id}
Test Webhook: POST /v1/webhooks/{webhook_id}/test

View Webhooks Documentation →

📊 Common Request/Response Patterns

Standard Success Response

{
  "success": true,
  "data": {
    "message_id": "msg_abc123",
    "status": "queued",
    "timestamp": "2025-12-10T12:30:00Z"
  }
}

Standard Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid phone number format",
    "details": "Phone number must be in E.164 format",
    "request_id": "req_xyz789",
    "timestamp": "2025-12-10T12:30:00Z"
  }
}

🚨 HTTP Status Codes

Code	Status	Description
`200`	OK	Request successful
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Authentication failed
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource not found
`409`	Conflict	Resource conflict
`422`	Unprocessable Entity	Validation failed
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error
`503`	Service Unavailable	Service temporarily unavailable

⚡ Rate Limits

Rate limits vary by plan and API:

Plan	SMS/Email	WhatsApp	Voice	Payments
Free	10/min	5/min	2/min	5/min
Starter	100/min	50/min	20/min	50/min
Growth	500/min	200/min	100/min	200/min
Enterprise	Custom	Custom	Custom	Custom

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1702317260

Handling Rate Limits

async function sendWithRetry(payload, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('https://api.afriroute.ai/api/v1/sms/send', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': apiKey
        },
        body: JSON.stringify(payload)
      });

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        console.log(`Rate limited. Retrying after ${retryAfter}s`);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      return await response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

🔒 Security

HTTPS Only

All API requests must use HTTPS. HTTP requests are rejected.

API Key Security

✅ Store keys securely (environment variables)
✅ Rotate keys regularly (every 90 days)
✅ Use separate keys for different environments
❌ Never commit keys to version control
❌ Never expose keys in client-side code

Request Signing (For Webhooks)

All webhooks include an X-AfriRoute-Signature header for verification.

Learn more about webhook security →

📱 Phone Number Format

All phone numbers must be in E.164 format:

+[country_code][number]

Examples

Country	Format	Example
🇪🇹 Ethiopia	`+251XXXXXXXXX`	`+251911234567`
🇰🇪 Kenya	`+254XXXXXXXXX`	`+254712345678`
🇳🇬 Nigeria	`+234XXXXXXXXXX`	`+2348012345678`
🇬🇭 Ghana	`+233XXXXXXXXX`	`+233241234567`
🇿🇦 South Africa	`+27XXXXXXXXX`	`+27821234567`

Validation

function validateE164(phoneNumber) {
  const e164Regex = /^\+[1-9]\d{1,14}$/;
  return e164Regex.test(phoneNumber);
}

// Usage
console.log(validateE164('+251911234567')); // true
console.log(validateE164('0911234567'));     // false

🌍 Country Coverage

AfriRoute supports messaging in 54+ African countries:

Region	Countries	SMS	WhatsApp	Voice
East Africa	ET, KE, TZ, UG, RW, BI	✅	✅	✅
West Africa	NG, GH, SN, CI, BF, ML	✅	✅	✅
Southern Africa	ZA, ZW, ZM, MW, MZ, BW	✅	✅	✅
North Africa	EG, MA, TN, DZ, LY	✅	✅	⚠️
Central Africa	CM, CD, CG, GA, TD, CF	✅	✅	⚠️

View complete coverage →

📦 SDKs & Libraries

Official SDKs for popular programming languages:

Language	Package	Documentation
JavaScript/Node.js	`npm install afriroute`	Docs →
Python	`pip install afriroute`	Docs →
C#	`dotnet add package AfriRoute`	Docs →
Go	`go get afriroute.ai/sdk-go`	Docs →

Quick Start with SDK

// JavaScript
const AfriRoute = require('afriroute');
const client = new AfriRoute('$AFRIROUTE_API_KEY');

await client.sms.send({
  to: '+251911234567',
  from: 'AFRIROUTE',
  text: 'Hello from AfriRoute!'
});

# Python
from afriroute import AfriRoute

client = AfriRoute('$AFRIROUTE_API_KEY')

client.sms.send(
    to='+251911234567',
    from_='AFRIROUTE',
    text='Hello from AfriRoute!'
)

🧪 Testing

Sandbox Environment

Test your integration without charges:

# Sandbox
https://sandbox.api.afriroute.ai

# Use test API key
$AFRIROUTE_API_KEY

Learn more about sandbox →

Postman Collection

Import our official Postman collection:

Download Collection →

📄 API Versioning

The API is versioned via URL path:

Current version: v1
https://api.afriroute.ai/api/v1/...

Version Policy

Breaking changes: New major version (v2, v3, etc.)
Non-breaking changes: Same version
Deprecation notice: 6 months before removal
Support: Previous version supported for 12 months

🆘 Support

📚 Documentation: docs.afriroute.ai
💬 Email: [email protected]
🔧 Status: docs status page
🐛 Issues: Support
💼 Sales: [email protected]

📚 Next Steps

Explore detailed documentation for each API:

Or start with our Getting Started Guide →

🌐 Base URLs​

🔑 Authentication​

API Key (Recommended)​

JWT Token​

📡 Available APIs​

1. SMS API​

2. WhatsApp API​

3. Email API​

4. Voice API​

5. USSD API​

6. Payments API​

7. Webhooks​

📊 Common Request/Response Patterns​

Standard Success Response​

Standard Error Response​

🚨 HTTP Status Codes​

⚡ Rate Limits​

Rate Limit Headers​

Handling Rate Limits​

🔒 Security​

HTTPS Only​

API Key Security​

Request Signing (For Webhooks)​

📱 Phone Number Format​

Examples​

Validation​

🌍 Country Coverage​

📦 SDKs & Libraries​

Quick Start with SDK​

🧪 Testing​

Sandbox Environment​

Postman Collection​

📄 API Versioning​

Version Policy​

🆘 Support​

📚 Next Steps​