Your account
Your plan
API documentation

SMS API

Single sends, bulk sends and delivery status.

POST /sms/send

Send one message to one recipient. Requires the sms.send scope (all standard keys have it).

Headers

x-api-keyrequiredYour API key
Content-Typerequiredapplication/json
Idempotency-KeyoptionalAny unique string (UUID recommended). Same key → same response, no double send.

Body

tostring, requiredRecipient, e.g. +233241234567
messagestring, requiredMessage text. Billed per segment.
sender_idstring, optionalAn approved Sender ID (max 11 chars). Defaults to your account default.
request 
curl -X POST https://tiansms.com/api/v1/sms/send 
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" 
  -d '{"to":"+233241234567","message":"Hi Ama, your order #1042 is ready for pickup.","sender_id":"AFIAFASHION"}'
200 OK 
{
  "success": true,
  "message": "SMS sent successfully",
  "data": { "message_id": "msg_7f3a2c1e", "cost": 0.04, "message_count": 1 }
}

POST /sms/bulk

Send the same message to many recipients in one call. Each number is processed and billed individually; the response lists per-number results.

toarray of strings, requiredRecipients. Keep batches to a few hundred numbers per request.
messagestring, requiredMessage text
sender_idstring, optionalApproved Sender ID
request 
curl -X POST https://tiansms.com/api/v1/sms/bulk 
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" 
  -d '{"to":["+233241234567","+233501234567","+233271234567"],"message":"PTA meeting Friday 4pm. Please attend.","sender_id":"ACCRAHIGH"}'
200 OK 
{
  "success": true,
  "message": "Bulk SMS processing completed",
  "data": {
    "total": 3, "sent": 3, "failed": 0, "total_cost": 0.12,
    "results": [
      { "to": "+233241234567", "status": "sent", "message_id": "msg_a1...", "cost": 0.04 },
      { "to": "+233501234567", "status": "sent", "message_id": "msg_b2...", "cost": 0.04 },
      { "to": "+233271234567", "status": "sent", "message_id": "msg_c3...", "cost": 0.04 }
    ]
  }
}

Personalised messages (different text per recipient)? Loop over /sms/send with an Idempotency-Key per recipient.

GET /sms/status/{message_id}

Current delivery status. Statuses: pending → sent → delivered or failed.

request 
curl https://tiansms.com/api/v1/sms/status/msg_7f3a2c1e -H "x-api-key: YOUR_API_KEY"
200 OK 
{
  "success": true,
  "data": {
    "message_id": "msg_7f3a2c1e",
    "recipient": "+233241234567",
    "sender_id": "AFIAFASHION",
    "status": "delivered",
    "error_message": null,
    "cost": 0.04,
    "message_count": 1,
    "created_at": "2026-10-09T09:14:02.000Z",
    "delivered_at": "2026-10-09T09:14:05.000Z",
    "failed_at": null
  }
}

Polling is fine for a handful of messages; for anything more, use webhooks.