API Documentation

Integrate FlixySMS into your applications

← Back to API Keys

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 doesn't 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