DirectSMS: REST API Migration Guide

The DirectSMS HTTP, HTTPS, REST and SOAP APIs are being switched off. To keep sending and receiving messages, you'll need to update your integration to use our new REST API.

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

Which DirectSMS API are you using?

Check the address your system calls today:

Step 1, Sender IDs and Step 3 are the same for everyone.

Before you start

• You need new API credentials. Your current DirectSMS username and password will not work with the new REST API. Keep them until your new key is sending.
• 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.

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 2A: If you use the HTTP API

What's different

Operation by operation

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

Sending an SMS (send_message)

Before:

https://api.directsms.com.au/s3/http/send_message?username=my_user&password=secret&type=2-way&messageid=APP1234&to=61412345678&message=Your+appointment+is+at+3pm

After:

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

{
  "messages": [
    {
      "content": "Your appointment is at 3pm",
      "destination_number": "+61412345678",
      "metadata": { "messageid": "APP1234" },
      "delivery_report": true
    }
  ]
}

Scheduling an SMS (schedule_message)

Before:

https://api.directsms.com.au/s3/http/schedule_message?username=my_user&password=secret&type=2-way&to=61412345678&message=Reminder&timestamp=1803942900

After:

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

{
  "messages": [
    {
      "content": "Reminder",
      "destination_number": "+61412345678",
      "scheduled": "2027-03-01T23:15:00.000Z"
    }
  ]
}

timestamp (seconds since the Unix epoch) becomes scheduled, the same time as an ISO 8601 date and time in UTC. For example, 1803942900 becomes 2027-03-01T23:15:00.000Z.

Cancelling a scheduled SMS (cancel_scheduled_message)

Before:

https://api.directsms.com.au/s3/http/cancel_scheduled_message?username=my_user&password=secret&id=4c2c7d229b4d56bf249e9f6192cb7c32

After:

curl -X PUT https://au.app.api.sinch.com/v1/messages/MESSAGE_ID \
  -u "API_KEY:API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"status": "cancelled"}'

Use the message_id returned when you scheduled the message. See Cancel scheduled message for details.

Getting replies and inbound messages (get_reply_messages, get_inbound_messages)

We recommend switching to a webhook (see Step 3), so replies are sent to your system as they arrive.

If you need to keep collecting them yourself, call GET /v1/replies, which returns both replies to your messages and messages sent to your inbound numbers. Then confirm the ones you've processed with POST /v1/replies/confirmed. See Step 3 for the old and new calls side by side, and for what to know before you switch.

Marking replies as read: on the HTTP API, replies were only marked as read if you set mark_as_read to any non-empty value. Leaving it out did not mark them. The new REST API never marks replies as read for you: confirm the ones you've processed, or they'll be returned again.

Responses and errors

DirectSMS returned errors with an HTTP 200 status, so check the status code of the new API's response, not just the body. The new REST API also returns 402 if your account has insufficient credit.

For example error responses, see Send messages.

Step 2B: If you use the HTTPS API

The HTTPS API (api.directsms.com.au/s3/https/…) has the same operations, parameters and responses as the HTTP API in Step 2A. Everything in Step 2A applies to it. Only the address is different.

Sending an SMS (send_message)

Before:

https://api.directsms.com.au/s3/https/send_message?username=my_user&password=secret&type=2-way&messageid=APP1234&to=61412345678&message=Your+appointment+is+at+3pm

After:

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

{
  "messages": [
    {
      "content": "Your appointment is at 3pm",
      "destination_number": "+61412345678",
      "metadata": { "messageid": "APP1234" },
      "delivery_report": true
    }
  ]
}

For the operations, the field changes, replies and the responses and errors, see Step 2A. The addresses in those examples change from s3/http to s3/https.

Step 2C: If you use the REST API

What's different

Operation by operation

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

Sending an SMS (sms/send)

Before:

curl -X POST https://api.directsms.com.au/s3/rest/sms/send \
  -H "Content-Type: application/json" \
  -H "Username: my_user" \
  -H "Password: secret" \
  -d '{
    "messageType": "2-way",
    "messageId": "APP1234",
    "messageText": "Your appointment is at 3pm",
    "to": ["61411000111", "61411000222"]
  }'

After:

curl -X POST https://au.app.api.sinch.com/v1/messages \
  -u "API_KEY:API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "content": "Your appointment is at 3pm",
        "destination_number": "+61411000111",
        "metadata": { "messageId": "APP1234" },
        "delivery_report": true
      },
      {
        "content": "Your appointment is at 3pm",
        "destination_number": "+61411000222",
        "metadata": { "messageId": "APP1234" },
        "delivery_report": true
      }
    ]
  }'

Scheduling an SMS (sms/schedule)

Use POST /v1/messages and add scheduled to each message, as in Step 2A above. scheduledDate becomes scheduled, which must be an ISO 8601 date and time in UTC, e.g. 2027-03-01T23:15:00.000Z. Epoch milliseconds are not accepted.

Cancelling a scheduled SMS (sms/deschedule)

Before:

curl -X DELETE https://api.directsms.com.au/s3/rest/sms/deschedule/1b71f477ef4bc6c50213642109fc537a \
  -H "Username: my_user" \
  -H "Password: secret"

After:

curl -X PUT https://au.app.api.sinch.com/v1/messages/MESSAGE_ID \
  -u "API_KEY:API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"status": "cancelled"}'

Use the message_id returned when you scheduled the message. See Cancel scheduled message for details.

Getting replies and inbound messages (sms/reply, sms/inbound)

We recommend switching to a webhook (see Step 3), so replies are sent to your system as they arrive.

If you need to keep collecting them yourself, call GET /v1/replies, which returns both replies and messages sent to your inbound numbers. See Step 3 for the old and new calls side by side, and for what to know before you switch.

Replies are no longer marked as read automatically. On the DirectSMS REST API, leaving markAsRead out marked replies as read, and only false left them unread. Now you confirm the ones you've processed with POST /v1/replies/confirmed, or they'll be returned again. See Replies for details.

Responses and errors

DirectSMS returned errors with an HTTP 500 status, so check the status code of the new API's response. The new REST API also returns 402 if your account has insufficient credit.

For example error responses, see Send messages.

Step 2D: If you use the SOAP API

What's different

Operation by operation

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

Sending an SMS (sendBrandedSmsMessage, sendTwoWaySmsMessage)

Before:

POST https://api.directsms.com.au/s3/soap/SmsGateway

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ns4="urn:SmsGateway">
  <SOAP-ENV:Body>
    <ns4:sendTwoWaySmsMessage>
      <connectionId xsi:type="xsd:string">CONNECTION_ID</connectionId>
      <twoWaySms xsi:type="ns4:TwoWaySmsMessage">
        <message xsi:type="xsd:string">Your appointment is at 3pm</message>
        <messageId>APP1234</messageId>
        <mobiles xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:string[1]">
          <item xsi:type="xsd:string">0412 345 678</item>
        </mobiles>
      </twoWaySms>
    </ns4:sendTwoWaySmsMessage>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

After:

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

{
  "messages": [
    {
      "content": "Your appointment is at 3pm",
      "destination_number": "+61412345678",
      "metadata": { "messageId": "APP1234" },
      "delivery_report": true
    }
  ]
}

Getting replies and inbound messages

We recommend switching to a webhook (see Step 3), so replies are sent to your system as they arrive.

If you need to keep collecting them yourself, call GET /v1/replies. It returns replies to your messages and messages sent to your inbound numbers together, so you no longer need separate operations for each. The markAsRead flag is replaced by confirming the replies you've processed with POST /v1/replies/confirmed. The new REST API never marks replies as read for you. See Step 3 for the old and new calls side by side, and for what to know before you switch.

Responses and errors

The REST API returns 400 if a request is invalid. The whole request is rejected, so check your numbers before sending. For example error responses, see Send messages.

Sender IDs

source_number sets the number or sender ID that a message shows as coming from. For the full rules, see source_number in Send messages. In short:

• Leave source_number out to send from your account's default number.
• If your account has more than one number, such as a dedicated number, set source_number to the one you want to use.
• Any sender ID or number you set must be registered to your account first. If it isn't, the message may fail to send, or may be sent from a different number.
• Alphanumeric sender IDs, such as your business name, must be registered before you use them. See Australia | Alphanumeric sender ID Registration. Then set source_number_type to ALPHANUMERIC.
• An alphanumeric sender ID can't receive replies. To let people reply, send from a number, such as your dedicated number.
• DirectSMS rejected a sender ID on 2-way messages sent with the HTTP API, and ignored it with the REST API. The new API uses the one you set, so check what your code sends.

Step 3: Delivery reports and replies

DirectSMS didn't have webhooks or delivery reports, and replies and inbound messages could only be collected by polling. Delivery reports and webhooks are new with the REST API.

Delivery reports

To get delivery reports for messages sent through the new REST API, add "delivery_report": true to each message. Then either:

• Use a webhook (recommended). Webhooks send delivery reports and replies to your system as they happen, and can be formatted to suit whatever your system expects. Create one under Settings → API Settings → Webhooks. See Webhooks Management for the options.
• Collect them yourself. Call GET /v1/delivery_reports, which returns up to 100 at a time, then confirm the ones you've processed with POST /v1/delivery_reports/confirmed. You can confirm up to 100 delivery reports in one request, and a successful call returns 202. See Delivery Reports for the request and response bodies.

Replies and inbound messages

We recommend a webhook. If you keep collecting replies yourself, swap the old calls for these:

Before:

https://api.directsms.com.au/s3/http/get_reply_messages?username=my_user&password=secret

After:

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

• GET /v1/replies returns replies to your messages and messages sent to your inbound numbers together, up to 100 per call. You can't filter by messageid or inbound_number.
• Confirm with POST /v1/replies/confirmed using the reply IDs, not message IDs, up to 100 per request. A successful call returns 202. See Replies for the request body.
• A dedicated inbound number is arranged with support. Sending a message doesn't create one.
• Retention is shorter. DirectSMS keeps replies and inbound messages for 12 months. The new endpoints keep them for 45 days. Anything already stored on DirectSMS won't appear in GET /v1/replies after you switch.

The fields you get back have new names, and they differ depending on the API and call you used:

On the new API, date_received is a date and time, not a number of seconds ago. content can be up to 5,000 characters, so it isn't cut short like the HTTP message field was. On a reply, destination_number is only included if the original message had a source number.

Checklist

• New key created under Basic Authentication, and the secret saved
• System supports TLS 1.2 at minimum (TLS 1.3 recommended)
• If you use the SOAP API: SOAP calls replaced with JSON requests
• Phone numbers in E.164 format (+61…), including numbers that start with 04, and with no spaces
• Numbers checked before sending
• No more than 100 messages per request
• Message text no longer than 5,000 characters
• messageid moved to metadata
• Schedule times changed to ISO 8601 UTC scheduled times
• Unicode text sent as plain text, not hexadecimal
• Sender IDs and numbers registered before you set them in source_number
• delivery_report: true added if you use delivery reports
• Your code saves the new message_id for each message, and cancels scheduled messages one at a time
• Replies received by webhook, or polling code confirms replies with POST /v1/replies/confirmed
• Code that reads replies and inbound messages uses the new field names

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 DirectSMS [HTTP API (api.directsms.com.au/s3/http) / HTTPS API (api.directsms.com.au/s3/https) / REST API (api.directsms.com.au/s3/rest) / SOAP API (api.directsms.com.au/s3/soap/SmsGateway or api.directsms.com.au/s3/services/SmsGateway)] 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. Remove connect/disconnect calls, convert phone numbers to E.164 format, move messageid into metadata, send Unicode as plain text instead of hexadecimal, convert schedule times to ISO 8601 UTC, and send no more than 100 messages per request.

FAQs

I already have DirectSMS API credentials. Do I still need a new key?
Yes. Credentials listed under Legacy API Credentials only work with the old DirectSMS APIs and will stop working when they're switched off.

Do I still need to call connect and disconnect?
No. Send your API key and secret in the Authorization header on every request. There are no sessions or connection IDs.

Does the new REST API support SOAP or XML?
No. All requests and responses are JSON.

How do I send 1-way and 2-way messages?
There's no type setting. Set source_number to the number or sender ID you want to send from, registered to your account (see Sender IDs). To let people reply, send from a number, such as your dedicated number. An alphanumeric sender ID can't receive replies.

I used max_segments to control costs. What should I do?
The new REST API splits long messages automatically, up to 5,000 characters in content. Check the length of your message in your own code before sending.

Do I still need to convert Unicode messages to hexadecimal?
No. Send the text as it is, e.g. "Hello World - 你好世界".

More information

• REST API documentation
• Developer guides
• Old DirectSMS docs: HTTP API, REST API, SOAP API