SMSFlow API Docs

Overview

Welcome to the SMSFlow API documentation. Our RESTful API allows you to programmatically send, track, and manage SMS messages, enabling seamless integration with your applications, CRM, or backend systems.

Base URL


                    https://api.smsflow.com.au/v2

Rate Limits

We currently enforce a soft limit of 10 requests per second (RPS). Please ensure you implement exponential backoff on retries to avoid unnecessary throttling.

Authentication

The SMSFlow API uses API Key authentication. You must include your secret API key in the Authorization header of every request.

Request Headers

Header	Value	Description
Content-Type	application/json	Required for all POST requests.
Authorization	Bearer YOUR_API_KEY	Your secret API key, obtained from the SMSFlow Developers area in your account settings.

Send SMS

Send a single message to one or more recipients. This endpoint returns a unique message_id for tracking status.

POST /sms/send

Example Request (cURL)


curl -X POST "https://api.smsflow.com.au/v2/messages/send" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{
           "to": "+61404123456",
           "from": "+61444123456",
           "body": "Your order #12345 is confirmed and will ship within 24 hours. Track it here: [link]",
           "callback_url": "https://yourdomain.com/sms/status"
         }'

Example Response (200 OK)

{
    "meta" : {
        "timezone" : "UTC"
    },
    "data" : {
        [
            "status": "queued",
            "message_id": "70718ec2581d4e118ae2f62f3e5941be",
            "attributes": {
                "body" : "message body you just sent",
                "number": "0404 123 456",
                "to" : "+61404123456",
                "contact" : "e897bbac165843f2b27a375897118199",
                "queue_time" : "2025-12-06 03:19:56",
                "credits_used" : 1,
                "warnings" : [ "Any warning that has not prevented the SMS being sent" ]
            }
        ]
    }
}

Body Parameters

Parameter	Type	Required	Description
to	String	YES	Recipient phone numbers in E.164 format (e.g., +61404123456)
contact_id	String	NO	Recipient contact ID (can be used instead of "to" field)
from	String	NO	Your registered Sender ID, pool ID or assigned dedicated number.
body	String	YES	The content of the SMS message. Max 160 characters (70 for Unicode).
callback_url	String	NO	Optional URL to receive webhook notifications for status updates.
reference	String	NO	Optional reference string for reporting and tracking.
delay	Int	NO	Delay in minutes to send the SMS.
send_at	String	NO	ISO date formatted string (YYYY-MM-DD HH:mm:00) to send the SMS.
send_at_timezone	String	NO	If using send_at field, can be used to send at specific timezone. If omitted, default timezone in account settings is used.

Message Status

Retrieve the current status of a message using its unique ID returned from the /sms/send endpoint.

GET /sms/status/{message_id}

Example Request (cURL)

curl -X GET 'https://api.smsflow.com.au/v2/sms/status/a16d8b7e746540d19a4b62a014295081?include_message=true' \
-H 'Authorization: Bearer YOUR_API_KEY'

Example Response (200 OK)

{
    "status": "Sent and confirmed from carrier",
    "destination": "+61404123456",
    "originator": "+61444123456",
    "delivery_time": "2025-12-06 03:19:56",
    "credits_used": 1,
    "encoding": "GSM_7BIT"
    "message": "Original message that was sent"
}

URL Parameters

Parameter	Value/s	Required	Description
include_message	true	NO	Includes the message body in the return. Default to false.

Account Balance

Check your current pre-paid credit balance to ensure uninterrupted service.

GET /account/balance

Example Request (cURL)

curl -X GET 'https://api.smsflow.com.au/v2/account/balance' \
-H 'Authorization: Bearer YOUR_API_KEY'

Example Response (200 OK)

{
  "account_id": "acc_001b2c3d4e5f6g",
  "credit_balance": 12500,
  "last_purchase_date": "2025-12-06 03:19:56"
}

Create Or Update Contact Using External Id

When maintining contacts from external sources, you can use this endpoint to update contact information based on their external Id. If they do not exist, they will be created otherwise they will be updated.

PUT /contacts/external_id/{external_id}

Example Request (cURL)

curl -X GET 'https://api.smsflow.com.au/v2/contacts/external_id/id1234' \
-H 'Authorization: Bearer YOUR_API_KEY'

Example Response (200 OK for updated or 201 Created for created)

{
  "status": "success",
  "contact_id": "457219a268524f399a13565650f6f09e",
  "created_at": "2025-12-06 03:19:56"
  "updated_at": "2025-12-06 03:19:56"
  "warnings": []
}

URL Parameters

Parameter	Value/s	Required	Description
external_id	String (50 chars max)	YES	External Id.

Body Parameters

Parameter	Type	Required	Description
first_name	String	YES (when creating)	Contact first name. Only required when creating new contacts
last_name	String	YES (when creating)	Contact last name. Only required when creating new contacts
phone_number	String	YES (when creating)	Contact phone. Must be a valid Australian mobile number otherwise the record will be rejected.
email	String	NO	Contacts email address
postcode	String	NO	Contacts postcode.
notes	String (500 chars max)	NO	Any notes about contact.