Skip to main content

​
Overview

This is the comprehensive API documentation for the Mifumo SMS API Version 2.0. It includes all endpoints with complete JSON request/response examples for SMS operations, white-label/partner management, and payment integration. Base URL: https://mifumosms.mifumolabs.com API Version: 2.0 Authentication: API Key (recommended) or JWT Bearer Token

​
Quick Start

​
Get Your API Key

  1. Register at https://mifumosms.mifumolabs.com
  2. Login to your account
  3. Navigate to API Settings → Generate API Key

​
Base URL Structure

Base URL: https://mifumosms.mifumolabs.com API Paths:
  • External SMS API: /api/integration/v1/
  • Authentication: /api/auth/
  • Messaging: /api/messaging/
  • Billing: /api/billing/
  • White-Label API: /api/integration/v1/partner/

​
Example Request

curl -X POST https://mifumosms.mifumolabs.com/api/integration/v1/sms/send/ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Hello from Mifumo SMS",
"recipients": ["+255614853618"],
"sender_id": "Quantum"
}'

​
API Structure

The API is organized into the following sections:

​
Authentication

Authorization: Bearer YOUR_API_KEY
or 
X-API-Key: YOUR_API_KEY

​
JWT Token (Web Applications)

  1. Login: POST /api/auth/login/
  2. Use access_token in Authorization header

​
Core SMS API

​
Send SMS

POST /api/integration/v1/sms/send/ Send SMS to one or more recipients. Request: 
{
"message": "Your message here",
"recipients": ["+255614853618", "+255614853619"],
"sender_id": "YourBrand",
"tenant_account_id": "uuid-optional-for-white-label"
}
Response: 
{
"success": true,
"message_id": "uuid-here",
"status": "sent"
}

​
Check Message Status

GET /api/integration/v1/sms/status// Response: 
{
"message_id": "uuid-here",
"status": "delivered",
"delivered_at": "2024-01-15T10:30:00Z"
}

​
Get SMS Balance

GET /api/integration/v1/sms/balance/ Response: 
{
"balance": 1000,
"currency": "credits"
}

​
White-Label / Partner API

Manage tenant accounts programmatically using your Customer API key. Tenants use your API key for all operations and do not have their own Mifumo SMS accounts.

​
Create Tenant Account

POST /api/integration/v1/partner/tenants/create/ Request: 
{
"tenant_name": "Customer Company Name",
"owner_email": "customer@example.com",
"owner_name": "John Doe",
"contact_phone": "+255123456789",
"initial_credits": 0
}
Response: 
{
"success": true,
"data": {
"mifumo_account_id": "a5245ef6-def7-4731-8c20-e89ef53aa65e",
"mifumo_account_id_public": "YCKWLWXX45W_TIAT1Y6BPW",
"mifumo_api_key": null,
"tenant_name": "Restaurant Chain A",
"tenant_id": "ec0a5041-65df-429e-8de5-3e2ac51ef332",
"sms_balance": 0,
"owner_email": "restaurant@example.com",
"created_at": "2025-12-20T11:35:48.898725+00:00"
}
}

​
Payment Integration

​
Payment Method: ZenoPay Mobile Money

All tenant payments use ZenoPay Mobile Money Integration. Payments go directly to Mifumo SMS. Tenants receive payment instructions on their phone and pay via mobile money. Credits are automatically added when payment completes. Supported Providers: vodacom, tigo, airtel, halotel

​
Initiate Payment for Tenant

POST /api/integration/v1/partner/tenants//payments/initiate/ Request: 
{
"package_id": "uuid-from-packages-list",
"buyer_email": "restaurant@example.com",
"buyer_name": "John Doe",
"buyer_phone": "0614853618",
"mobile_money_provider": "vodacom"
}
Response: 
{
"success": true,
"data": {
"transaction_id": "uuid-here",
"order_id": "MIFUMO-20251220-ABC12345",
"amount": 18000,
"currency": "TZS",
"status": "pending"
}
}

​
Rate Limiting

API requests are rate-limited to prevent abuse:
  • Authenticated requests: 1000 requests per hour
  • Unauthenticated requests: 100 requests per hour
Rate limit headers are included in responses: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1638000000

​
Pagination

List endpoints support pagination with the following query parameters:
  • page (integer): Page number (default: 1)
  • page_size (integer): Items per page (default: 20, max: 100)
Pagination response format: 
{
  "count": 150,
  "next": "https://api.example.com/endpoint/?page=2",
  "previous": null,
  "results": [...]
}

​
Date Formats

All dates are returned in ISO 8601 format: 
2025-11-27T10:30:00Z
When sending dates in requests, use the same format or:
  • Date only: 2025-11-27
  • Date and time: 2025-11-27T10:30:00Z

​
Phone Number Format

Phone numbers should be in E.164 format:
  • ✅ Correct: +255614853618
  • ❌ Incorrect: 0614853618, 255614853618
The API will attempt to normalize phone numbers, but it’s recommended to send them in E.164 format.

​
Error Handling

​
HTTP Status Codes

CodeDescription
200OK - Request successful
201Created - Resource created
400Bad Request - Invalid parameters
401Unauthorized - Invalid authentication
403Forbidden - Insufficient permissions
404Not Found - Resource not found
429Too Many Requests - Rate limit exceeded
500Internal Server Error

​
Error Response Format

{
"error": "Error message description",
"code": "ERROR_CODE",
"details": {}
}

​
Code Examples

​
JavaScript (Fetch)

const response = await
fetch('https://mifumosms.mifumolabs.com/api/integration/v1/sms/send/', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
message: 'Hello from Mifumo SMS',
recipients: ['+255614853618'],
sender_id: 'Quantum'
})
});
const data = await response.json();
console.log(data);

​
Python (Requests)

import requests
url = 'https://mifumosms.mifumolabs.com/api/integration/v1/sms/send/'
headers = {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
data = {
'message': 'Hello from Mifumo SMS',
'recipients': ['+255614853618'],
'sender_id': 'Quantum'
}
response = requests.post(url, json=data, headers=headers)
print(response.json())

​
Support

For API support, contact:
Last Updated: December 2025 API Version: 2.0