Developers

API documentation

Send SMS, check your balance and request sender IDs from your own system with simple JSON requests.

Base URL: https://sms.spindlesoftware.com/api

Authentication

Every request needs your API key in the X-API-Key header. Find it under Developers in your dashboard.

X-API-Key: your_api_key_here

Check your balance

GET/api/v1/balance

Response

{
  "success": true,
  "sms_balance": 1000
}

Send an SMS

POST/api/v1/sms/send

Body

{
  "sender_id": "MyBrand",
  "contacts": "[260950001234,260971005678]",
  "message": "Hello from MyBrand"
}

Response

{
  "success": true,
  "message": "SMS queued for delivery.",
  "credits_used": 2,
  "balance_remaining": 998,
  "provider_response": { ... }
}

Request a sender ID

POST/api/v1/sender-id

Body

{
  "sender_id": "MyBrand"
}

Sender IDs are letters and numbers only, up to 11 characters. The request is reviewed by an admin; you can send with it once it is approved.

Response (202)

{
  "success": true,
  "message": "Sender ID submitted for approval.",
  "sender_id": "MyBrand",
  "status": "pending"
}

Rate limits

Good to know

Message safety checks

Every message is checked before sending. Besides the normal success response, POST /api/v1/sms/send can return:

StatusMeaning
207 "partial": trueOnly some recipients were sent; failed_contacts lists the rest, and their credits were returned.
202 "status": "held"Held for review. Credits are reserved and returned if it is not approved.
422 "reasons"Blocked because it looks like a scam. No credits are used.
429The daily limit for the shared sender ID has been reached.
403The sender ID is not approved for your account, or the account is suspended.

See the acceptable use policy for what is not allowed.