DARSMS API Documentation
Quick Start
Generate an API key in the API Keys page, then switch languages below to copy a ready-to-use integration sample.
Base URL: https://dev.darsms.co.tz/api/v1
Auth Header: X-API-Key: your_api_key
Sender ID: pass the approved sender label, for example DARSMS
Rate Limit: 180 requests/minute per API key (payment endpoints are capped at 10/minute)
Format: Tanzanian numbers like 2557XXXXXXXX or +2557XXXXXXXX
1. Send SMS
Send one message to one or many recipients. Response includes batchId and messageIds for delivery tracking.
curl -X POST "https://dev.darsms.co.tz/api/v1/integrations/sms/send" \
-H "Content-Type: application/json" \
-H "X-API-Key: darsms_xxxxxxxxxxxxxxxxxxxxxxxxxx" \
-d '{
"senderId": "DARSMS",
"to": ["255712345678", "255754321987"],
"message": "Dear James, your payment is due on 2026-05-05."
}'2. List Sender IDs
List your approved sender IDs. Use a returned senderId label as the senderId value when sending.
curl -X GET "https://dev.darsms.co.tz/api/v1/integrations/sender-ids" \
-H "X-API-Key: darsms_xxxxxxxxxxxxxxxxxxxxxxxxxx"3. Check Balance
Fetch the current SMS balance for the account.
curl -X GET "https://dev.darsms.co.tz/api/v1/integrations/balance" \
-H "X-API-Key: darsms_xxxxxxxxxxxxxxxxxxxxxxxxxx"4. Check Message Status
Look up delivery state for a single message using the messageId returned from the send response.
curl -X GET "https://dev.darsms.co.tz/api/v1/integrations/sms/status/<messageId>" \
-H "X-API-Key: darsms_xxxxxxxxxxxxxxxxxxxxxxxxxx"5. Buy SMS Credits
Initiate a purchase for the given quantity. The payer receives a mobile-money push prompt on payerPhone; credits are added automatically once payment is confirmed.
curl -X POST "https://dev.darsms.co.tz/api/v1/integrations/purchases" \
-H "Content-Type: application/json" \
-H "X-API-Key: darsms_xxxxxxxxxxxxxxxxxxxxxxxxxx" \
-d '{
"quantitySms": 1000,
"payerPhone": "255712345678"
}'6. Purchase History
List all SMS credit purchases. Filter with ?status=PENDING|SUCCESS|FAILED|CANCELLED and paginate with ?page= & ?limit=.
curl -X GET "https://dev.darsms.co.tz/api/v1/integrations/purchases?status=ALL&page=1&limit=20" \
-H "X-API-Key: darsms_xxxxxxxxxxxxxxxxxxxxxxxxxx"7. Retry / Repay Payment
Re-send the payment push for a pending, failed, or cancelled purchase. Pass an optional phone to send the push to a different number.
curl -X POST "https://dev.darsms.co.tz/api/v1/integrations/purchases/<purchaseId>/pay" \
-H "Content-Type: application/json" \
-H "X-API-Key: darsms_xxxxxxxxxxxxxxxxxxxxxxxxxx" \
-d '{ "phone": "255712345678" }'Response Format
All endpoints return a consistent JSON envelope.
Send SMS — 202 response
{
"success": true,
"message": "Manual SMS queued",
"data": {
"batchId": "550e8400-e29b-41d4-a716-446655440000",
"queued": 3,
"duplicatesRemoved": 1,
"senderId": "DARSMS",
"messageIds": [
"a1b2c3d4-...",
"e5f6g7h8-...",
"i9j0k1l2-..."
]
}
}List Sender IDs — 200 response
{
"success": true,
"message": "Approved sender IDs",
"data": [
{
"id": "clx8p2q10000...",
"senderId": "DARSMS",
"status": "APPROVED",
"approvedAt": "2026-05-01T09:00:00.000Z",
"createdAt": "2026-05-01T08:55:00.000Z"
}
]
}Use a returned senderId as the senderId value when calling Send SMS. Only approved sender IDs are returned.
Check Message Status — 200 response
{
"success": true,
"message": "Message status",
"data": {
"id": "a1b2c3d4-...",
"recipientPhone": "255712345678",
"status": "DELIVERED",
"sentAt": "2026-05-07T10:00:00.000Z",
"deliveredAt": "2026-05-07T10:00:05.000Z",
"errorMessage": null
}
}Possible status values: QUEUED → SENT → DELIVERED or FAILED
Buy SMS Credits — 201 response
{
"success": true,
"message": "Purchase initiated",
"data": {
"purchaseId": "clx8p2q10000...",
"transactionRef": "SNP-8F3A19C2",
"amount": 25000,
"unitPrice": 25,
"quantitySms": 1000,
"providerStatus": "pending",
"expiresAt": "2026-05-07T14:00:00.000Z",
"efdReceipt": false
}
}The payer approves the mobile-money prompt on their phone; credits are added to the wallet automatically once the payment is confirmed.
Purchase History — 200 response
{
"success": true,
"message": "Purchase history",
"data": [
{
"purchaseId": "clx8p2q10000...",
"invoiceNumber": "INV-20260507-2Q1000",
"quantitySms": 1000,
"unitPrice": 25,
"subtotalAmount": 25000,
"vatAmount": 0,
"totalAmount": 25000,
"currency": "TZS",
"efdReceipt": false,
"status": "SUCCESS",
"paymentStatus": "SUCCESS",
"transactionRef": "SNP-8F3A19C2",
"channel": "mobile_money",
"canRetry": false,
"createdAt": "2026-05-07T13:00:00.000Z",
"updatedAt": "2026-05-07T13:01:12.000Z"
}
],
"meta": { "page": 1, "limit": 20, "total": 1 }
}Retry / Repay Payment — 200 response
{
"success": true,
"message": "Payment push triggered",
"data": {
"pushed": true,
"reinitiated": false,
"transactionRef": "SNP-8F3A19C2"
}
}Works for PENDING, FAILED, and CANCELLED purchases. When the old intent has expired a new one is created and reinitiated is true.
Error Format
{
"success": false,
"message": "Invalid API key",
"details": null
}Common statuses: 401 invalid key, 403 inactive company/account, 422 validation errors, 429 rate limit.