Send SMS from your own system

One HTTP request sends a message. Use it for OTPs, payment confirmations, order updates — anything your app needs to tell a customer.

Quick start

Live in three steps

  1. 1
    Create an account
    and get an approved Sender ID.
  2. 2
    Generate an API key
    in Dashboard → API Keys. Keep it on your server only.
  3. 3
    Send your first SMS
    with the request on the right.
Get your API key
curl -X POST https://pigasms.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "ZAWADI",
    "to": ["+255712345678", "+255754111222"],
    "message": "Habari! Order yako imefika."
  }'
Reference

Endpoints

Base URL https://pigasms.com/api/v1. Send JSON with the header Authorization: Bearer YOUR_API_KEY.

MethodEndpointDescription
POST /send Send an SMS to one or many numbers
GET /messages/{id} Get a message and its status
GET /campaigns/{id} Get a send: how many were sent, failed or are still queued
GET /balance Check your remaining credits
GET /senderids List your Sender IDs and their status

to takes one number or a list of up to 10,000. Optional: schedule_at to send later, reference (your own ID, sent back in webhooks) and the header Idempotency-Key, so a request your system retries is never sent twice.

Response

What you get back

Each recipient gets its own message ID so you can track it individually.

201 Created — POST /send
{
  "campaign_id": 1024,
  "status": "sending",
  "test": false,
  "reference": "order-1001",
  "recipients": 2,
  "credits_used": 2,
  "balance": 18448,
  "scheduled_at": null,
  "opted_out": 0,
  "invalid": [],
  "messages": [
    { "id": 99201, "to": "+255712345678", "status": "sent", "parts": 1, "network": "Yas" },
    { "id": 99202, "to": "+255754111222", "status": "queued", "parts": 1, "network": "Vodacom" }
  ]
}
Webhooks

Status updates, pushed to you

Add a webhook URL in your dashboard. When a message you sent through the API is accepted by the network or fails, we send a signed POST like this:

POST https://your-site.co.tz/sms-callback
PigaSMS-Signature: t=1795267500,v1=5f2c9a…
{
  "id": "evt_8ea66a2ee7c976bae8f0d4b5",
  "event": "message.sent",
  "created": "2026-11-21T14:25:03+03:00",
  "test": false,
  "data": {
    "id": 99201,
    "campaign_id": 1024,
    "to": "+255712345678",
    "sender": "ZAWADI",
    "status": "sent",
    "parts": 1,
    "network": "Yas",
    "test": false,
    "reference": "order-1001",
    "delivery": null,
    "error": null,
    "created_at": "2026-11-21T14:25:02+03:00",
    "sent_at": "2026-11-21T14:25:03+03:00"
  }
}

Events: message.sent (accepted by the network), message.failed, and later message.delivered or message.undelivered when the phone network reports whether it reached the phone (delivery in data). In the sandbox every sent message is delivered at once.

Reply with HTTP 200. Otherwise we try again after 1 minute, 5 minutes, 30 minutes and up to 24 hours. Check the PigaSMS-Signature header with your webhook secret: the dashboard shows how.

Errors

Error codes

Errors return JSON with a code for your program and a message explaining what went wrong.

CodeMeaning
400
Bad request
The body is not valid JSON.
401
Unauthorized
API key missing, invalid or revoked.
402
Insufficient credits
Top up your balance and try again.
403
Forbidden
The request came from an address the key does not allow, or the account is suspended.
404
Not found
No such endpoint, message or campaign on your account.
422
Validation failed
E.g. Sender ID not approved, invalid phone number or empty message.
429
Too many requests
Slow down — retry after the time given in the Retry-After header.

Sandbox mode

Use a test key (ps_test_…) to try every endpoint without sending real SMS or spending credits. Messages to 255700000001 always fail, so you can test failures too.

Security

HTTPS only. Keep keys on your server, make one per system, revoke any of them at once from the dashboard, and limit each key to your server IPs.

Rate limits

120 requests a minute per key, each with up to 10,000 numbers. Need more? Talk to us.

Build with PigaSMS

Create a free account to get your sandbox and live API keys.