DARSMS API Documentation

Use these integration APIs to send SMS, buy credits, and track payments 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 (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

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

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

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

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

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

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

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.

API overview

Authentication: Every request is made over HTTPS and authenticated with an API key sent in the X-API-Key header. Create and revoke keys in the API Keys section of your dashboard. Keep keys on your server only.
Sending SMS: POST a sender ID, one or more recipient numbers in international format (255...) and the message text to the send endpoint. The response includes a batch ID and a message ID per recipient.
Sender ID: Pass the label of an approved sender ID, such as DARSMS or your own custom Sender ID. List the sender IDs available to your account with the sender IDs endpoint.
Delivery reports: Use the message ID to query the message status endpoint. Statuses are queued, sent, delivered, failed and rejected. Contact us if your integration needs delivery callbacks.
Responses and errors: Responses are JSON with a success flag, a message and a data object. Errors set success to false, include a readable message and use standard HTTP status codes: 401 invalid key, 403 inactive account, 422 validation error and 429 rate limit.

New to the API? Start with the SMS API overview, read the SMS API integration guide, or see how teams use it for OTP verification.

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

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

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

{ "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": "Approved sender IDs", "data": [ { "id": "clx8p2q10000...", "senderId": "DARSMS", "status": "APPROVED", "approvedAt": "2026-05-01T09:00:00.000Z", "createdAt": "2026-05-01T08:55:00.000Z" } ] }

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

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

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

API overview

Authentication

Every request is made over HTTPS and authenticated with an API key sent in the X-API-Key header. Create and revoke keys in the API Keys section of your dashboard. Keep keys on your server only.

Sending SMS

POST a sender ID, one or more recipient numbers in international format (255...) and the message text to the send endpoint. The response includes a batch ID and a message ID per recipient.

Sender ID

Pass the label of an approved sender ID, such as DARSMS or your own custom Sender ID. List the sender IDs available to your account with the sender IDs endpoint.

Delivery reports

Use the message ID to query the message status endpoint. Statuses are queued, sent, delivered, failed and rejected. Contact us if your integration needs delivery callbacks.

Responses and errors

Responses are JSON with a success flag, a message and a data object. Errors set success to false, include a readable message and use standard HTTP status codes: 401 invalid key, 403 inactive account, 422 validation error and 429 rate limit.