API Documentation

Use these integration APIs to send SMS from your platform securely.

Create account

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

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

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. Check Balance

Fetch the current SMS balance for the account.

cURL

curl -X GET "https://dev.darsms.co.tz/api/v1/integrations/balance" \
  -H "X-API-Key: darsms_xxxxxxxxxxxxxxxxxxxxxxxxxx"

3. Check Message Status

Look up delivery state for a single message using the messageId returned from the send response.

cURL

curl -X GET "https://dev.darsms.co.tz/api/v1/integrations/sms/status/<messageId>" \
  -H "X-API-Key: darsms_xxxxxxxxxxxxxxxxxxxxxxxxxx"

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-..."
    ]
  }
}

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

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.

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." }'

{ "success": true, "message": "Manual SMS queued", "data": { "batchId": "550e8400-e29b-41d4-a716-446655440000", "queued": 3, "duplicatesRemoved": 1, "senderId": "DARSMS", "messageIds": [ "a1b2c3d4-...", "e5f6g7h8-...", "i9j0k1l2-..." ] } }

{ "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 } }