One HTTP request sends a message. Use it for OTPs, payment confirmations, order updates — anything your app needs to tell a customer.
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." }'
$ch = curl_init('https://pigasms.com/api/v1/send'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'sender' => 'ZAWADI', 'to' => ['+255712345678'], 'message' => 'Habari! Order yako imefika.', ]), ]); $response = json_decode(curl_exec($ch), true);
import requests res = requests.post( "https://pigasms.com/api/v1/send", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={ "sender": "ZAWADI", "to": ["+255712345678"], "message": "Habari! Order yako imefika.", }, ) print(res.json())
const res = await fetch("https://pigasms.com/api/v1/send", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ sender: "ZAWADI", to: ["+255712345678"], message: "Habari! Order yako imefika.", }), }); console.log(await res.json());
Base URL https://pigasms.com/api/v1. Send JSON with the header Authorization: Bearer YOUR_API_KEY.
| Method | Endpoint | Description |
|---|---|---|
| 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.
Each recipient gets its own message ID so you can track it individually.
{
"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" }
]
}
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:
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 return JSON with a code for your program and a message explaining what went wrong.
| Code | Meaning |
|---|---|
| 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. |
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.
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.
120 requests a minute per key, each with up to 10,000 numbers. Need more? Talk to us.
Create a free account to get your sandbox and live API keys.