> ## Documentation Index
> Fetch the complete documentation index at: https://docs-sms.mifumolabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Mifumo SMS API Documentation - Version 2.0

## 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](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](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

```bash theme={null}
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:

* [Core SMS API](#core-sms-api) - Send SMS, check status, balance, and delivery reports
* [White-Label / Partner API](#white-label--partner-api) - Manage tenant accounts programmatically
* [Payment Integration](#payment-integration) - ZenoPay Mobile Money Integration
* [Authentication](#authentication) - API Key and JWT token authentication
* [Error Handling](#error-handling) - HTTP status codes and error formats
* [Code Examples](#code-examples) - JavaScript, Python, and PHP examples

## Authentication

### API Key (Recommended)

```
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:**

```json theme={null}
{
"message": "Your message here",
"recipients": ["+255614853618", "+255614853619"],
"sender_id": "YourBrand",
"tenant_account_id": "uuid-optional-for-white-label"
}
```

**Response:**

```json theme={null}
{
"success": true,
"message_id": "uuid-here",
"status": "sent"
}
```

### Check Message Status

**GET /api/integration/v1/sms/status/{message_id}/**

**Response:**

```json theme={null}
{
"message_id": "uuid-here",
"status": "delivered",
"delivered_at": "2024-01-15T10:30:00Z"
}
```

### Get SMS Balance

**GET /api/integration/v1/sms/balance/**

**Response:**

```json theme={null}
{
"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:**

```json theme={null}
{
"tenant_name": "Customer Company Name",
"owner_email": "customer@example.com",
"owner_name": "John Doe",
"contact_phone": "+255123456789",
"initial_credits": 0
}
```

**Response:**

```json theme={null}
{
"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/{tenant_id}/payments/initiate/**

**Request:**

```json theme={null}
{
"package_id": "uuid-from-packages-list",
"buyer_email": "restaurant@example.com",
"buyer_name": "John Doe",
"buyer_phone": "0614853618",
"mobile_money_provider": "vodacom"
}
```

**Response:**

```json theme={null}
{
"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:

```json theme={null}
{
  "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

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

### Error Response Format

```json theme={null}
{
"error": "Error message description",
"code": "ERROR_CODE",
"details": {}
}
```

## Code Examples

### JavaScript (Fetch)

```javascript theme={null}
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)

```python theme={null}
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:

* **Email**: [support@mifumolabs.com](mailto:support@mifumolabs.com)
* **Base URL**: [https://mifumosms.mifumolabs.com](https://mifumosms.mifumolabs.com)

***

**Last Updated**: December 2025
**API Version**: 2.0