API documentation

Getting started

From sign-up to your first delivered SMS in about five minutes.

1. Create an account and buy a plan

Create an account, then pick a plan and pay with MTN MoMo, Telecel Cash, AT Money or card. Your API key is emailed to you shortly after your first purchase; paste it in My Account → API & developers to connect your dashboard.

2. Authenticate

Send your key in the x-api-key header on every request. Never put the key in client-side code (browser or mobile app) — call our API from your server.

      
      terminal
    

curl https://tiansms.com/api/v1/account/balance 
  -H "x-api-key: YOUR_API_KEY"

      
      response
    

{ "success": true, "data": { "balance": 198.4, "currency": "GHS" } }

3. Send your first SMS

      
      terminal
    

curl -X POST https://tiansms.com/api/v1/sms/send 
  -H "x-api-key: YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" 
  -d '{"to":"+233241234567","message":"Akwaaba! Your Tian SMS account is live.","sender_id":"TianSMS"}'

The Idempotency-Key header is optional but recommended: if your request times out and you retry with the same key, we return the original result instead of sending (and charging) twice.

4. Check delivery

      
      terminal
    

curl https://tiansms.com/api/v1/sms/status/msg_7f3a... -H "x-api-key: YOUR_API_KEY"

Or skip polling entirely and receive delivery webhooks.

Usage statistics

      
      terminal
    

curl "https://tiansms.com/api/v1/account/usage?days=30" -H "x-api-key: YOUR_API_KEY"

      
      response
    

{
  "success": true,
  "data": {
    "period_days": 30,
    "sms": { "total_sent": 1240, "delivered": 1215, "failed": 25, "delivery_rate": "97.98", "total_cost": 49.6, "total_segments": 1302 },
    "otp": { "total_sent": 310, "verified": 288, "verification_rate": "92.90", "total_cost": 15.5 },
    "api": { "total_requests": 2, "total_spend": 65.1 }
  }
}

Good to know

Rate limits: 100 requests per 15 minutes per key. Watch RateLimit-Remaining; on 429 wait for RateLimit-Reset. Need more? Ask us.
Sender IDs: up to 11 letters/digits, registered with the networks on your behalf. Request yours in My Account → Sender IDs; until approved, use TianSMS.
Message length: 160 GSM characters per segment (153 when concatenated); 70 / 67 for Unicode (emoji, Twi diacritics). Each segment is billed as one unit.
IP whitelisting & spend caps: available on request — we lock your key to your server IPs and cap daily spend.