FlowSMS API Reference

Welcome to the FlowSMS API. Our RESTful API allows you to seamlessly integrate carrier-grade messaging directly into your applications. All requests must be made over HTTPS and use JSON payloads.

Authentication

Authenticate your API requests using a Bearer token in the Authorization header or by providing the X-API-Key header. You can generate API keys from your portal dashboard.

HTTP Header

Authorization: Bearer YOUR_API_KEY
// OR
X-API-Key: YOUR_API_KEY

POST /api/v1/sms/send

Dispatches an SMS message to a specified recipient. The cost of the message is calculated dynamically based on the destination network and message length.

Parameter	Description
to string Required	Recipient phone number in E.164 format (e.g. `+15550192834`).
text string Required	The message body. Long messages will be automatically split and concatenated.
sender_id string	Custom alphanumeric Sender ID (up to 11 characters). Default is `FLOWSMS`.

cURL Example

curl -X POST https://flowsms.cc/api/v1/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+447700900077",
    "text": "Your verification code is 123456.",
    "sender_id": "AUTH"
  }'

JSON Response

{
  "success": true,
  "message_id": "msg_9f8e7d6c",
  "cost": 0.045,
  "status": "queued"
}

GET /api/v1/balance

Retrieve your current available wallet balance.

cURL Example

curl -X GET https://flowsms.cc/api/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /api/v1/rates

Query the current SMS termination rate for a specific country or prefix.

Parameter	Description
prefix string Required	The country calling code (e.g. `44`, `1`).

cURL Example

curl -X GET "https://flowsms.cc/api/v1/rates?prefix=44" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /api/v1/messages

Retrieve a paginated list of your sent messages and their delivery statuses.

JSON Response

{
  "success": true,
  "data": [
    {
      "message_id": "msg_9f8e7d6c",
      "recipient": "+447700900077",
      "status": "delivered",
      "sent_at": "2026-10-02T14:30:00Z"
    }
  ],
  "pagination": { "page": 1, "total_pages": 5 }
}

Webhook HMAC Signatures

To securely verify that incoming webhook payloads originate from FlowSMS, we sign all requests using HMAC-SHA256. The signature is included in the X-FlowSMS-Signature header.

1. Extract the raw request body as a string.
2. Retrieve the X-FlowSMS-Signature header.
3. Compute the HMAC-SHA256 hash of the raw body using your Webhook Secret.
4. Compare the computed hash (hex-encoded) to the signature header.

Node.js Example

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const hash = crypto.createHmac('sha256', secret)
                     .update(rawBody)
                     .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(signature));
}