API documentation

API reference

One REST API for SMS, OTP and contacts. JSON in, JSON out, one header to authenticate.

Base URL

https://tiansms.com/api/v1

Authentication

x-api-key: <your key>

Format

Content-Type: application/json

Rate limit

100 requests / 15 min per key (RateLimit-* headers)

Endpoints

Method	Path	Purpose	Docs
POST	`/sms/send`	Send one SMS	SMS
POST	`/sms/bulk`	Send the same message to many numbers	SMS
GET	`/sms/status/{message_id}`	Delivery status of a message	SMS
POST	`/otp/send`	Generate and send a one-time passcode	OTP
POST	`/otp/verify`	Verify a passcode	OTP
GET POST	`/contacts`	List / create contacts	Contacts
GET PUT DELETE	`/contacts/{id}`	Read / update / delete a contact	Contacts
GET	`/account/balance`	Wallet balance in GHS	Getting started
GET	`/account/usage?days=30`	Usage statistics	Getting started

Response shape

Every response is JSON with the same three top-level keys. Check success first; on failure message is human-readable.

OK

{
  "success": true,
  "message": "SMS sent successfully",
  "data": { "message_id": "msg_7f3a...", "cost": 0.04, "message_count": 1 }
}

      
Bad Request
    

{
  "success": false,
  "message": "Missing required fields: to, message"
}

Phone number format

Use international format for Ghana: +233241234567. Local format 0241234567 is accepted and normalised. All three networks (MTN, Telecel, AirtelTigo) are reachable.

Next steps

Getting started — get a key and send your first message.
Webhooks — receive delivery reports on your server.
Error codes — what each status means and how to handle it.
Playground — call the live API from your dashboard.