SMS Broadcast: REST API Migration Guide

The SMS Broadcast Basic API (api.php) and Advanced API (api-adv.php) are being switched off. To keep sending messages, you'll need to update your integration to use our REST API.

This guide only covers what changes. For full details on every endpoint and field, see the REST API documentation.

Before you start

• You need new API credentials. Your current SMS Broadcast API credentials will not work with the REST API.
• Your system must support TLS 1.2 at minimum. We recommend TLS 1.3. Older systems may fail to connect, usually with a generic connection or handshake error.
• Requests use JSON. You send an HTTPS POST with a JSON body instead of URL parameters.

Step 1: Create your REST API key

Everyone migrating must do this, even if you already have API credentials.

1. Log in at https://app.sinch.com.
2. Go to Settings → API Settings.
3. In the Basic Authentication section, click Create new key.
4. Copy your API key and API secret straight away and store them somewhere safe. The secret is only shown once, when the key is created. If you lose it, you'll need to create a new key.

Send your key and secret in an HTTP Basic Authorization header on every request. The value is your key and secret joined by a colon, then Base64-encoded:

Authorization: Basic base64(API_KEY:API_SECRET)

Check it works: replace API_KEY and API_SECRET with your own, then run the request below. It only reads data, so no messages are sent.

curl https://au.app.api.sinch.com/v1/delivery_reports \
  -u "API_KEY:API_SECRET" \
  -H "Accept: application/json"

A 200 response means your key works (the list may be empty). A 401 means the key or secret is wrong.

Step 2: Update your API calls

What's different

The tables below only show the fields you need to change. For every field and its limits, see Send messages.

Sending an SMS (Basic API)

Before:

https://api.smsbroadcast.com.au/api.php?username=myuser&password=mypass&to=0400111222&message=Hello%20world

After:

POST https://au.app.api.sinch.com/v1/messages
Authorization: Basic <base64(API_KEY:API_SECRET)>
Content-Type: application/json

{
  "messages": [
    {
      "content": "Hello world",
      "destination_number": "+61400111222"
    }
  ]
}

Sending an SMS (Advanced API)

Before:

https://api.smsbroadcast.com.au/api-adv.php?username=myuser&password=mypass&to=0400111222&message=Hello%20World&ref=112233&maxsplit=5&delay=15

After:

POST https://au.app.api.sinch.com/v1/messages
Authorization: Basic <base64(API_KEY:API_SECRET)>
Content-Type: application/json

{
  "messages": [
    {
      "content": "Hello World",
      "destination_number": "+61400111222",
      "metadata": { "ref": "112233" },
      "delivery_report": true,
      "scheduled": "2027-03-01T23:15:00.000Z"
    }
  ]
}

Responses and errors

For example error responses, see Send messages.

Checking your balance

Call GET /v1/credits_management/account to get your remaining credits. You can also see your balance in the web app at https://app.sinch.com.

curl https://au.app.api.sinch.com/v1/credits_management/account \
  -u "API_KEY:API_SECRET" \
  -H "Accept: application/json"

The response looks like this:

{
  "remaining_credits": {
    "MT_MMS": 20,
    "MT_SMS": 1024
  },
  "related_account": "VendorName:RelatedAccountName",
  "expiry": "2018-01-12T12:12:12.122Z"
}

• MT_SMS and MT_MMS are your remaining SMS and MMS credits. A balance is left out if one hasn't been set.
• The balance check only works for prepaid accounts. Other accounts get a 404.

See Get credit balance for details.

Step 3: Delivery reports and replies

What you need to do depends on how you receive delivery reports (status updates) and replies today.

If you use webhooks

Webhooks send delivery reports and replies to your system as they happen. You can see yours under Settings → API Settings → Webhooks. If the list is empty, you don't use webhooks and can skip to the next section.

To check that your system handles the new IDs:

1. Find where your system reads the message ID from your webhook. If it expects a whole number (for example, a number type or an integer database column), change it to accept text.
2. If your webhook itself needs changing, you can edit it in the web app under Settings → API Settings → Webhooks. See Webhooks Management for the options.
3. Add "delivery_report": true to each message you send through the REST API.
4. Send a test message through the REST API and check that your system receives the delivery report and handles the ID.

If you check by calling the API

If you don't use webhooks, you can keep checking for delivery reports and replies by calling the API. Message IDs are text (UUIDs) rather than numbers, and phone numbers are in E.164 format. Add "delivery_report": true to each message you send through the REST API.

Checklist

• New key created under Basic Authentication, and the secret saved
• System supports TLS 1.2 at minimum (TLS 1.3 recommended)
• Phone numbers in E.164 format (+61…)
• Numbers checked before sending, because one invalid number stops the whole request
• No more than 100 messages per request
• delivery_report: true added if you use delivery reports
• ref moved to metadata, and delay changed to an ISO 8601 UTC scheduled time
• Your code reads JSON responses instead of OK: / BAD: / ERROR: text
• Your code handles message IDs as text (UUIDs) and phone numbers that start with a +
• If you use webhooks: your system accepts message IDs as text (UUIDs), not just whole numbers

Using an AI coding assistant

Our documentation has a version made for AI tools such as Claude, ChatGPT or Cursor. See AI Integration in the REST API documentation. You could start with a prompt like:

Update my code to stop using the SMS Broadcast Advanced API (api-adv.php) and use the Sinch REST API instead (POST https://au.app.api.sinch.com/v1/messages, HTTP Basic authentication, JSON). Use the documentation at https://developers.app.sinch.com/llms.txt. Convert phone numbers to E.164 format, move ref into metadata, change delay to an ISO 8601 UTC scheduled time, and send no more than 100 messages per request.

FAQs

I already have SMS Broadcast API credentials. Do I still need a new key?
Yes. Credentials listed under Legacy API Credentials only work with the old SMS Broadcast API and will stop working when it's switched off.

Can I keep sending GET requests with my details in the URL?
No. The REST API only accepts POST requests with a JSON body, and your credentials go in the Authorization header rather than the URL.

I used maxsplit to control costs. What should I do?
The REST API splits long messages automatically and doesn't cap the number of parts. Check the length of your message in your own code before sending.

If one number in my list is invalid, will the other messages still send?
Not with the REST API. If any number in a request is invalid, the whole request is rejected and none of its messages are sent. Check your numbers before sending.

Do I need to set up my status update and inbound URLs again?
No. If you receive delivery reports or replies by webhook, Sinch is moving your existing webhooks for you, so you don't need to set up a new one. Message IDs for messages you send through the REST API are UUIDs (text), not whole numbers, so check that your system can handle them (see Step 3). If you check by calling the API instead, there's nothing to set up.

More information

• REST API documentation
• Developer guides
• Old SMS Broadcast docs: Basic API, Advanced API