API Documentation

Integrate FlixySMS into your applications

← Back to API Keys

Developer summary

The FlixySMS API is a REST interface for SMS, WhatsApp, status, and received-message workflows

The FlixySMS API is a REST API that lets developers send single messages, send bulk batches, check delivery status, and retrieve received SMS or WhatsApp replies. Each request uses bearer-token authentication, and the API can route through a selected Android or WhatsApp device when a device identifier is provided.

Key facts

  • Bearer-token authentication is required through the Authorization header.
  • Default rate limiting is documented as 100 API requests per minute.
  • The bulk endpoint accepts up to 100 recipients per request.
  • The received messages endpoint returns 25 messages per page and supports device, sender, and date filters.

Process

  1. 1First, create an API key in the FlixySMS dashboard.
  2. 2Next, send the bearer token in the Authorization header.
  3. 3Then, call /api/v1/message/send for a single message or /api/v1/message/bulk for a batch.
  4. 4Finally, poll the status endpoint or retrieve received replies through /api/v1/message/received.

Base URL

https://flixysms.com/api/v1

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Rate Limiting

API requests are rate limited to 100 requests per minute by default. Rate limit information is included in response headers:

  • • X-RateLimit-Limit: Maximum requests per minute
  • • X-RateLimit-Remaining: Remaining requests in current window
  • • X-RateLimit-Reset: Unix timestamp when the rate limit resets
POST/api/v1/sms/send
Also available at:/api/v1/message/send

Send a single SMS or WhatsApp message. Supports media attachments (PDF, images, videos, documents) when using a WhatsApp device.

Headers

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

Request Body

{
  "to": "+1234567890",
  "message": "Check out this document!",
  "device_id": "optional-device-uuid",
  "media_url": "https://example.com/document.pdf"
}

Parameters

toRequired. Recipient phone number in international format
messageRequired. Message text (used as caption when media is attached)
device_idOptional. Specific device UUID. If omitted, auto-selects an online device
media_urlOptional. URL to media file. Supports: PDF, images (JPEG, PNG, GIF, WebP), videos (MP4, WebM), audio (MP3, OGG, WAV), documents (DOC, DOCX, TXT, ZIP). Only works with WhatsApp devices.

Response

{
  "success": true,
  "message_id": "123e4567-e89b-12d3-a456-426614174000",
  "device_id": "987e6543-e89b-12d3-a456-426614174000",
  "status": "queued",
  "to": "+1234567890",
  "message": "Hello from FlixySMS!",
  "media_url": "https://example.com/document.pdf"
}

Code Examples

curl
curl -X POST \
  "https://flixysms.com/api/v1/sms/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+1234567890",
  "message": "Check out this document!",
  "device_id": "optional-device-uuid",
  "media_url": "https://example.com/document.pdf"
}'
javascript
const response = await fetch('https://flixysms.com/api/v1/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "to": "+1234567890",
      "message": "Check out this document!",
      "device_id": "optional-device-uuid",
      "media_url": "https://example.com/document.pdf"
    })
});

const data = await response.json();
console.log(data);
python
import requests

response = requests.post(
    'https://flixysms.com/api/v1/sms/send',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
      "to": "+1234567890",
      "message": "Check out this document!",
      "device_id": "optional-device-uuid",
      "media_url": "https://example.com/document.pdf"
    }
)

print(response.json())
php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://flixysms.com/api/v1/sms/send');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode({
      "to": "+1234567890",
      "message": "Check out this document!",
      "device_id": "optional-device-uuid",
      "media_url": "https://example.com/document.pdf"
    }));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
POST/api/v1/sms/bulk
Also available at:/api/v1/message/bulk

Send messages to multiple recipients (max 100 per request). Supports media attachments when using a WhatsApp device.

Headers

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

Request Body

{
  "recipients": [
    "+1234567890",
    "+0987654321",
    "+1122334455"
  ],
  "message": "Check out this document!",
  "device_id": "optional-device-uuid",
  "media_url": "https://example.com/document.pdf"
}

Parameters

recipientsRequired. Array of phone numbers in international format (max 100)
messageRequired. Message text (used as caption when media is attached)
device_idOptional. Specific device UUID. If omitted, auto-selects an online device
media_urlOptional. URL to media file. Same media is sent to all recipients. Only works with WhatsApp devices.

Response

{
  "success": true,
  "message_ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "223e4567-e89b-12d3-a456-426614174001",
    "323e4567-e89b-12d3-a456-426614174002"
  ],
  "device_id": "987e6543-e89b-12d3-a456-426614174000",
  "stats": {
    "total": 3,
    "valid": 3,
    "invalid": 0,
    "queued": 3
  }
}

Code Examples

curl
curl -X POST \
  "https://flixysms.com/api/v1/sms/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "recipients": [
    "+1234567890",
    "+0987654321",
    "+1122334455"
  ],
  "message": "Check out this document!",
  "device_id": "optional-device-uuid",
  "media_url": "https://example.com/document.pdf"
}'
javascript
const response = await fetch('https://flixysms.com/api/v1/sms/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "recipients": [
        "+1234567890",
        "+0987654321",
        "+1122334455"
      ],
      "message": "Check out this document!",
      "device_id": "optional-device-uuid",
      "media_url": "https://example.com/document.pdf"
    })
});

const data = await response.json();
console.log(data);
python
import requests

response = requests.post(
    'https://flixysms.com/api/v1/sms/bulk',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
      "recipients": [
        "+1234567890",
        "+0987654321",
        "+1122334455"
      ],
      "message": "Check out this document!",
      "device_id": "optional-device-uuid",
      "media_url": "https://example.com/document.pdf"
    }
)

print(response.json())
php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://flixysms.com/api/v1/sms/bulk');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode({
      "recipients": [
        "+1234567890",
        "+0987654321",
        "+1122334455"
      ],
      "message": "Check out this document!",
      "device_id": "optional-device-uuid",
      "media_url": "https://example.com/document.pdf"
    }));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
GET/api/v1/sms/status/:message_id
Also available at:/api/v1/message/status/:message_id

Check the delivery status of a sent message

Headers

{
  "Authorization": "Bearer YOUR_API_KEY"
}

Response

{
  "success": true,
  "data": {
    "message_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "delivered",
    "delivered_at": "2024-01-15T10:31:00Z",
    "device_id": "987e6543-e89b-12d3-a456-426614174000"
  }
}

Code Examples

curl
curl -X GET \
  "https://flixysms.com/api/v1/sms/status/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"
javascript
const response = await fetch('https://flixysms.com/api/v1/sms/status/123e4567-e89b-12d3-a456-426614174000', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);
python
import requests

response = requests.get(
    'https://flixysms.com/api/v1/sms/status/123e4567-e89b-12d3-a456-426614174000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY'
    }
)

print(response.json())
php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://flixysms.com/api/v1/sms/status/123e4567-e89b-12d3-a456-426614174000');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);


$response = curl_exec($ch);
curl_close($ch);

echo $response;
GET/api/v1/messages/received
Also available at:/api/v1/message/received

Retrieve received SMS and WhatsApp messages with pagination (25 per page)

Headers

{
  "Authorization": "Bearer YOUR_API_KEY"
}

Query Parameters

page1 (optional, default: 1)
device_iduuid (optional, filter by device)
from+1234567890 (optional, filter by sender number)
since2024-01-01T00:00:00Z (optional, ISO date)
until2024-01-31T23:59:59Z (optional, ISO date)

Response

{
  "success": true,
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "from": "+1234567890",
      "message": "Hello, this is a test message",
      "received_at": "2024-01-15T10:30:00Z",
      "device_id": "987e6543-e89b-12d3-a456-426614174000",
      "device_name": "My Phone",
      "device_phone": "+0987654321",
      "type": "sms",
      "metadata": {
        "sim_slot": 1
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 100,
    "total_pages": 4,
    "has_more": true
  }
}

Code Examples

curl
curl -X GET \
  "https://flixysms.com/api/v1/messages/received?page=1&device_id=987e6543-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"
javascript
const response = await fetch('https://flixysms.com/api/v1/messages/received?page=1&device_id=987e6543-e89b-12d3-a456-426614174000', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);
python
import requests

response = requests.get(
    'https://flixysms.com/api/v1/messages/received?page=1&device_id=987e6543-e89b-12d3-a456-426614174000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY'
    }
)

print(response.json())
php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://flixysms.com/api/v1/messages/received?page=1&device_id=987e6543-e89b-12d3-a456-426614174000');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY'
]);


$response = curl_exec($ch);
curl_close($ch);

echo $response;

Error Responses

The API returns standard HTTP status codes to indicate success or failure of requests.

400

Bad Request

The request was invalid or missing required parameters

401

Unauthorized

Invalid or missing API key

403

Forbidden

API key does not have permission for this endpoint

429

Too Many Requests

Rate limit exceeded

503

Service Unavailable

No devices available to send SMS

FlixySMS - Professional SMS Marketing Platform | Bulk SMS campaigns Gateway