touchSMS API

The touchSMS REST API lets you send SMS and MMS, manage contacts, groups and opt-outs, read inbound messages, run phone number verification (OTP) and manage webhook subscriptions.

All requests must be made over HTTPS to https://app.touchsms.com.au/api. Request and response bodies are JSON. Timestamps are ISO 8601 in UTC.

SMS

Send SMS and MMS messages, one at a time or up to 1000 in a single request. Each message in a request is validated on its own. Valid messages are queued and returned in `data.messages`; any that fail come back in `data.errors` with an `error_code` and an `error_help` explaining the fix, so one bad number doesn't block the rest of a batch. Messages can be scheduled with `date`, tagged with a `campaign` or `reference` for reporting, and carry up to 10 `metadata` key/value pairs that are returned with delivery receipts and replies. Every message is checked against an opt-out list before it is sent. Use the dry-run endpoint to validate a request and see parts and cost without sending. See [Sending messages](/guides/sending-messages/) for MMS rules, error codes and testing numbers.

Templates

Message templates saved on your touchSMS account. Templates are shared between the API and the [web app](https://app.touchsms.com.au): create, update and delete them here, and they show up in the app, and the other way round. To send with a template, use its `message` as the `body` of a send and its `sender_id` as `from`. Merge fields aren't filled in for you, so replace them with your own values before sending.

Groups

Contact groups, used to message many contacts at once from the web app. Groups are read-only over the API. To add a contact to a group, pass `group` with the group's title when you create the contact; the group is created if it doesn't exist yet. See [Contacts and groups](/guides/contacts-and-groups/).

Contacts

The people in your address book. You don't need contacts to send messages, but keeping them in sync means your team sees names in conversations, inbound messages and reports. A contact needs a `number`; name, email, groups and custom fields are optional. To keep one contact per number, create with `update_if_exists: true`, which updates the existing contact instead of adding a duplicate. List endpoints are paginated and support search and sorting. See [Contacts and groups](/guides/contacts-and-groups/).

Opt-outs

Numbers that have asked not to receive messages. Opt-outs are recorded automatically when a recipient replies with a keyword such as `STOP` or uses an opt-out link, and you can add or remove them here, for example to sync opt-outs from your own CRM. Sends to an opted-out number are rejected with `RECIPIENT_OPTED_OUT` and aren't sent. Each opt-out belongs to an opt-out list. Without a list, it goes on your account's default list. Subscribe to the `optout_created` webhook to hear about new opt-outs as they happen. See [Opt-outs](/guides/opt-outs/).

Opt-out lists

Lists that keep opt-outs separate, for example one per brand or per type of message. Every account has a default list, created automatically. Sends are checked against the default list unless the request names a different one with `opt_out_list_id` or `opt_out_list_name`, so someone who opts out of marketing can still get appointment reminders. Lists are created in the web app; over the API you can read them and the opt-outs they hold. See [Opt-outs](/guides/opt-outs/).

Account

Details of the account your API key belongs to, and the sender IDs it can send from. A sender ID is what a recipient sees a message as coming from: a dedicated number, a verified phone number, an alphanumeric name, or `SHARED_NUMBER` for the shared pool. Use the sender ID endpoints to find a valid `from` before sending. Pass a recipient's number to get only the sender IDs that are valid for that recipient's country.

Inbound messages

Replies and other messages received by your numbers. Inbound messages that are replies to something you sent carry that message's `metadata`, so you can match them to records in your system. Polling this endpoint works, but the `message_received` webhook delivers each message as it arrives and is the better choice for most integrations. See [Webhooks](/guides/webhooks/).

List inbound messages
GET /v2/inbounds

Verify

Phone number verification with one-time codes sent by SMS. Create a verification to send a code to a number, then check the code the user enters. Codes expire after a set time and can be cancelled, by ID or for every pending verification to a number. You control the code length, expiry and message template. Verification doesn't limit how many times a code can be checked, so add your own limit on attempts. These endpoints are under `/v3`. See [Verify](/guides/verify/).

Webhook subscriptions

Have touchSMS call your own URL when something happens on your account. You can subscribe to four events: `message_received` (an inbound message), `message_dlr` (a delivery receipt), `optout_created` (a new opt-out) and `message_received_3cx`. Each subscription has a target URL, a request method and optional headers. The URL can't point at one of our own domains. See [Webhooks](/guides/webhooks/) for each event's payload and how to verify signatures.