![\"Logo\"](\"https://i.imgur.com/TSlhWi2.png\")
Want to jump right in and test our APIs? Hit the Run in Postman button in the top right to launch Postman.\nPostman is free & lets you test and debug API requests.
You can run the examples for each request by expanding them in the top right.
\n![\"Examples\"](\"https://assets.postman.com/postman-docs/accessing-saved-examples.jpg\")
https://app.touchsms.com.au/api/v2\nAll API requests require an API key. You can generate them by logging into your account, and visiting the API Keys page under Settings in the sidebar.
Click the Create API Key button and enter a name for your key. The system will generate you a new set of API credentials, which consist of an Access Token and a\nToken ID.
When making requests to the API, credentials are passed using Basic Authentication.
\nThe Access Token is used as the username, and the Token ID is used as the password. These\nare labelled this way on the API Keys page to make the mapping clear.
Most programming languages and http clients allow you select basic authentication and pass the username/password. For languages that do not support automatically adding basic auth, you must pass a header, formatted as follows.
\nAuthorization: Basic <credentials>\n<credentials> is the Base64 encoding of the Access Token and Token ID joined by a single colon :.
For example, in PHP:
\n$header = \"Authorization: Basic \" . base64_encode($accessToken . \":\" . $tokenId)\nIn Postman, you\ncan preset your credentials for all requests by clicking the collection name in the (Called touchSMS) and then entering the Access Token in the Username field\nand the Token ID in the Password field.
![\"Basic](\"https://assets.postman.com/postman-docs/basic-auth.jpg\")
For security purposes, all requests to our API must be made over HTTPs.
\nIf an API Key is missing, malformed, or invalid, you will receive a 401 Unauthorized response code and the following JSON response:
{\n \"message\": \"Unauthenticated.\"\n}\nIf you intend to integrate our API into your website, ensure that you do not make requests directly from the user's browser (i.e. from javascript) as this means\nyour API is exposed to anyone visiting your website.
\nYou should add an endpoint for form handler to your backend to process messages. Remember that you are responsible for any messages send through your account,\nso ensure you have adequate spam prevention.
\nEndpoints that return a list of resources are paginated. Use the page query param to move through\nthe results:
GET /v2/contacts?page=2\nPaginated responses wrap the results in a data array, alongside links and meta objects\ndescribing the current position in the result set:
{\n \"data\": [\n // ... resources for this page\n ],\n \"links\": {\n \"first\": \"https://app.touchsms.com.au/api/v2/contacts?page=1\",\n \"last\": \"https://app.touchsms.com.au/api/v2/contacts?page=8\",\n \"prev\": null,\n \"next\": \"https://app.touchsms.com.au/api/v2/contacts?page=2\"\n },\n \"meta\": {\n \"current_page\": 1,\n \"from\": 1,\n \"last_page\": 8,\n \"path\": \"https://app.touchsms.com.au/api/v2/contacts\",\n \"per_page\": 50,\n \"to\": 50,\n \"total\": 400\n }\n}\nRather than incrementing page yourself, follow links.next until it is null. This is the safest\nway to walk a full result set.
The contacts and groups endpoints accept a per_page query param, between 10 and 200:
GET /v2/contacts?per_page=200\nOther endpoints use a fixed page size and will ignore per_page. Current defaults:
| Endpoint | \nDefault page size | \nAccepts per_page | \n
|---|---|---|
| /v2/contacts | \n50 | \nYes (10 to 200) | \n
| /v2/groups | \n50 | \nYes (10 to 200) | \n
| /v2/inbounds | \n100 | \nNo | \n
| /v2/optouts | \n15 | \nNo | \n
| /v2/webhook-subscriptions | \n25 | \nNo | \n
Do not rely on these defaults staying fixed. Read meta.per_page from the response if your\nintegration needs to know the page size it was served.
Not every list endpoint is paginated. /v2/templates and /v2/account/sender-ids return the full\nset in a data array with no links or meta. Check for the presence of meta rather than\nassuming it is there.
All request timestamps show be formatted as ISO8601, e.g. YYYY-MM-DDTHH:MM:SS. The timezone is always UTC.
Always check if your API call was successful or resulted in error. You may check the following
\nPlease check the table below for common error constants. Note that some API functions can return custom errors of their own (listed in appropriate document\nsections). Check the error response for details, e.g. which field caused an error or which resource you don’t have access to.
\n| Status Code | \nError | \nDescription | \n
|---|---|---|
| 200 | \n\n | Request Successful. | \n
| 422 | \nValidation Failed | \nThere was a validation error. Check the supplied response for more details. | \n
| 402 | \nNot enough credits | \nIf your account is out of SMS Credits the system will issue a 402 Payment Required response. | \n
| 401 | \nAuthentication failed | \nIf your API Keys are invalid or disabled the system will issue a 401 response. | \n
| 405 | \nMethod Not Allowed | \nIf your application tries to make a GET Request to the API the system will issue a 405 Method Not Allowed response. | \n
To troubleshoot your connection you should be prepared to use Google. If you don't receive a status code, there is probably some kind of networking issue between your server and us.
\nCheck your network topology, firewalls, proxies and other network components that maybe causing your server to not be able to connect.
\nIf you are receiving an error status code, first check the request body for detailed error information.
\nIf you've already tried to diagnose the problem and you still can't get requests to work, please create a ticket through our support system. You must have detailed information about your problem, see below for a template.
\nAPI endpoint being used?
\ni.e. /api/v2/sms
Language being used?
\ni.e. php, C#, etc
Are you using the relevant library or package?
\nY/N
\nHave you tested the failing request in Postman? If not, please reproduce the issue there
\nY/N
\nWhat are you trying to achieve with the API request?
\ni.e. I'm trying to send a sms message to a client with a custom sender ID,
\nWhat error(s) are you getting from the API? Include the description given in the response.
\ni.e. Number is opted out
NB: WE MUST HAVE A HTTP REQUEST/RESPONSE CAPTURE (Without this we cannot help you)
\nAcceptable formats for this are:
\nPlease provide the output of attempting the relevant API call with curl, as provided on the API's documentation page.
\nIf possible, please provide a copy of the relevant source code making the request.
\nIf you wish to conduct testing during development without actually sending SMSes, you can use the numbers below.\nThese can also be used in integration tests (we suggest setting up a separate test account for this purpose).\nSent messages will not be visible in your account.
\n61491578888
\nThis will cause the API to skip saving this message, but return a result as if it was a normally processed message
\n61491570156
\nThis will cause the API to respond with an error that the number is not valid
\n61491570157
\nThis will cause the API to respond like the number is opted out
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Authentication","slug":"authentication"},{"content":"Testing Numbers","slug":"testing-numbers"}],"owner":"14542603","collectionId":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","publishedId":"2sBY4SMJsn","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-07-29T00:25:09.000Z"},"item":[{"name":"Messages","item":[{"name":"Send SMS / MMS","id":"0035f38f-68a1-423a-87f4-2c617798912a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"{{baseUrl}}/v2/sms","description":"You can post up to 1000 messages with each API call. If only a portion of messages fail, the successful ones will be sent.
If sending MMS messages, you are limited to 10 messages per API call.
\nYou must send requests to this endpoint using application/json due to the nested structure of the data.
You can supply up to 10 key/value pairs as metadata with each message, allowing your integration to identify and associate delivery receipt and inbound replies\nwith entities in your system.
\nEach key may be up to 50 characters and must be a string. Each value may be up to 100 characters and may be a string or an integer.
\nTo send as MMS message, use the media property (array). You can attach a single image, up to a size limit of 1MB.\nMMS messages are limited to 10 per request, and are not supported in all countries.
{\n \"messages\": [\n {\n \"from\": \"+61412345678\",\n // Must be an MMS supported virtual number\n \"to\": \"+61412345678\",\n \"body\": \"Body text, up to 1600 characters\",\n \"metadata\": {\n \"mms_subject\": \"My MMS Subject\"\n // Specify MMS subject, up to 40 chars\n },\n \"media\": [\n // Publically accessible file, up to 1MB. jpg, png, gif supported.\n \"https://example.com/my_image.jpg\"\n ]\n }\n ]\n}\nThe request body should consist of an array with the key messages, containing each individual message to be sent.
| Key | \nType | \nDescription | \nRequired | \nDefault | \n
|---|---|---|---|---|
| to | \nstring | \nDestination phone number. Ideally in E164 international format including the leading +, ie +61412345678. Local formatting will be parsed but is not recommended. | \n Yes | \n\n |
| from | \nstring | \nSender ID, either a a Dedicated Number, Verified Phone Number, Verified Alphanumeric Sender ID. When using numbers, use E164 format. To send using the shared pool, use the string \"SHARED_NUMBER\" | \nYes | \n\n |
| body | \nstring | \nMessage content, up to 1600 characters. Unicode is accepted. | \nYes | \n\n |
| campaign | \nstring | \nCustom campaign name. Shown in reports. | \n\n | API Campaign (%date%) | \n
| metadata | \nobject | \nCustom metadata to associate with the message. Will be returned with delivery receipts and inbound messages that are replies. | \n\n | \n |
| media | \narray | \nSupply a single image URL to send message as an MMS. See MMS section above. | \n\n | \n |
| reference | \nstring | \nCustom reporting reference. Available in exported reports and delivery receipts. | \n\n | \n |
| date | \ndatetime | \nSchedule a message at a specific time. Must be in ISO8601 format in UTC timezone. Eg 2021-02-17T22:52:07Z | \n\n | \n |
The following parameters can be included at the root level of the request (alongside the messages array):
| Key | \nType | \nDescription | \nRequired | \nDefault | \n
|---|---|---|---|---|
| opt_out_list_id | \ninteger | \nID of an existing opt-out list to check recipients against. Recipients found in this list will be rejected with error code RECIPIENT_OPTED_OUT. Cannot be used with opt_out_list_name. | \n\n | \n |
| opt_out_list_name | \nstring | \nName of an existing opt-out list to check recipients against. Recipients found in this list will be rejected with error code RECIPIENT_OPTED_OUT. Cannot be used with opt_out_list_id. | \n\n | \n |
| reject_duplicates | \nboolean | \nWhen true, prevents sending duplicate messages with the same from, to, and body within this request. Duplicates will be filtered out before processing. | \n\n | false | \n
| reject_duplicates_by_recipient | \nboolean | \nWhen true, prevents sending duplicate messages to the same recipient (to field) within this request, regardless of from or body content. Only the first message to each recipient will be sent. | \n\n | false | \n
You can prevent messages from being sent to recipients who have opted out by specifying an opt-out list. Use either the list ID or name (but not both):
\n{\n \"opt_out_list_id\": 123,\n \"messages\": [\n {\n \"from\": \"+61412345678\",\n \"to\": \"+61412345679\",\n \"body\": \"Your message here\"\n }\n ]\n}\nOr using the list name:
\n{\n \"opt_out_list_name\": \"Marketing Opt-Outs\",\n \"messages\": [\n {\n \"from\": \"+61412345678\",\n \"to\": \"+61412345679\",\n \"body\": \"Your message here\"\n }\n ]\n}\nYou can prevent duplicate messages within a single request using the duplicate rejection options:
\n{\n \"reject_duplicates\": true,\n \"messages\": [\n {\n \"from\": \"+61412345678\",\n \"to\": \"+61412345679\",\n \"body\": \"Your message here\"\n },\n {\n \"from\": \"+61412345678\",\n \"to\": \"+61412345679\",\n \"body\": \"Your message here\"\n }\n ]\n}\nIn this example, only the first message would be sent as they have identical from, to, and body values.
\nAlternatively, use reject_duplicates_by_recipient to allow only one message per recipient:
{\n \"reject_duplicates_by_recipient\": true,\n \"messages\": [\n {\n \"from\": \"+61412345678\",\n \"to\": \"+61412345679\",\n \"body\": \"First message\"\n },\n {\n \"from\": \"+61412345680\",\n \"to\": \"+61412345679\",\n \"body\": \"Second message\"\n }\n ]\n}\nIn this example, only the first message would be sent as both messages are going to the same recipient.
\nThe response will contain both successful and failed messages. Successful messages will be returned in the data.messages[] array, and include the same keys as\nthe request. A meta object is also returned for each message, which contains information about the message length, cost, etc
{\n \"status\": \"VALID\",\n \"to\": \"61476647930\",\n \"from\": \"ALPHASENDER\",\n \"body\": \"hello world\",\n \"campaign\": \"API Campaign (2021-07-05)\",\n \"reference\": null,\n \"date\": null,\n \"meta\": {\n \"size\": 11,\n \"parts\": 1,\n \"is_unicode\": false,\n \"cost\": 1,\n \"country\": \"AU\"\n }\n}\nFailed messages will be returned in the data.errors[] array, and will contain the input data (same keys) along with the error_code and error_help\nproperties.\nPlease see the table below for possible error codes. The error_help field should be logged in your system, as this contains human-readable information on how\nto resolve the error.
If your account does not have sufficient credits to complete a send, a 406 HTTP code will be returned.
\n{\n \"message\": \"Insufficient credits\",\n \"required\": 102,\n \"balance\": 11,\n \"is_postpaid\": false\n}\n| Key | \nDescription | \n
|---|---|
| INVALID_MEDIA | \nMMS media failed validation. Please see MMS docs. | \n
| INVALID_BODY | \nMessage body was invalid or missing. | \n
| INVALID_METADATA | \nMetadata failed validation. Please see metadata docs. | \n
| INVALID_RECIPIENT | \nRecipient is invalid or could not be parsed.P Pass number as E164 where possible. | \n
| INVALID_SCHEDULE | \nSchedule date is invalid. | \n
| INVALID_SENDER_ID | \nSender ID is invalid. | \n
| UNAPPROVED_SENDER_ID | \nSender ID is not allowed or approved for account. Please register the sender ID in your account's allowed sender ID page under settings. | \n
| RECIPIENT_OPTED_OUT | \nRecipient opted out from communications. | \n
This endpoint performs all the validation done by the \"Send SMS\" endpoint, and provides calculations credit usage and message length.
\nMessages posted to this endpoint are not sent.
\nSee the documentation for the \"Send SMS\" endpoint.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","name":"touchSMS V2 Documentation","type":"collection"}},"urlObject":{"path":["v2","sms","dry"],"host":["{{baseUrl}}"],"query":[],"variable":[]}},"response":[{"id":"de676fe0-04dc-47e5-b58f-dbab14928277","name":"Send SMS Dry","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"reject_duplicates_by_recipient\": false,\n \"messages\": [\n {\n \"to\": \"0476647930\",\n \"from\": \"ALPHASENDER\",\n \"body\": \"hello world\"\n },\n {\n \"to\": \"04123\",\n \"from\": \"61412345678\",\n \"body\": \"invalid number\"\n },\n {\n \"to\": \"0476647930\",\n \"from\": \"TOOOOOOOOOLONG\",\n \"body\": \"invalid sender\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"{{baseUrl}}/v2/sms/dry"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"meta\": {\n \"totalParts\": 1,\n \"totalMessages\": 1,\n \"totalCredits\": 1,\n \"creditBalance\": 1000,\n \"hasSufficientCredits\": true\n },\n \"messages\": [\n {\n \"status\": \"VALID\",\n \"to\": \"61476647930\",\n \"from\": \"ALPHASENDER\",\n \"body\": \"hello world\",\n \"campaign\": \"API Campaign (2021-07-05)\",\n \"reference\": null,\n \"date\": null,\n \"meta\": {\n \"size\": 11,\n \"parts\": 1,\n \"is_unicode\": false,\n \"cost\": 1,\n \"country\": \"AU\"\n }\n }\n ],\n \"errors\": [\n {\n \"status\": \"ERROR\",\n \"error_code\": \"INVALID_RECIPIENT\",\n \"to\": \"04123\",\n \"from\": \"61412345678\",\n \"body\": \"invalid number\",\n \"campaign\": null,\n \"reference\": null,\n \"date\": null\n },\n {\n \"status\": \"ERROR\",\n \"error_code\": \"INVALID_SENDER_ID\",\n \"to\": \"61476647930\",\n \"from\": \"TOOOOOOOOOLONG\",\n \"body\": \"invalid sender\",\n \"campaign\": null,\n \"reference\": null,\n \"date\": null\n }\n ]\n }\n}"}],"_postman_id":"ad63942a-e521-4748-9220-a5d28729e6cc"}],"id":"116925ad-9331-436b-a764-69fdb0031ab9","_postman_id":"116925ad-9331-436b-a764-69fdb0031ab9","description":"","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","name":"touchSMS V2 Documentation","type":"collection"}}},{"name":"Templates","item":[{"name":"List Templates","id":"1fe1616f-6ed7-40c0-864b-44cbce245e99","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"application/json"}],"url":"{{baseUrl}}/v2/templates","description":"Returns the message templates on your account, ordered by name.
\nThis endpoint returns all active templates in a single response and is not paginated.
\nGET /v2/templates\n{\n \"data\": [\n {\n \"id\": 1234,\n \"user\": 5678,\n \"name\": \"Appointment Reminder\",\n \"message\": \"Hi {{firstname}}, reminder of your appointment tomorrow.\",\n \"replies\": true,\n \"sender_id\": \"SHARED_NUMBER\",\n \"updated\": \"2024-03-11T02:14:07Z\",\n \"created\": \"2024-02-02T23:51:19Z\"\n }\n ]\n}\n| Field | \nType | \nDescription | \n
|---|---|---|
| id | \ninteger | \nTemplate ID | \n
| user | \ninteger | \nID of the user the template belongs to | \n
| account | \ninteger | \nAccount ID. Only present on templates shared across an account | \n
| name | \nstring | \nTemplate name | \n
| message | \nstring | \nTemplate body. May contain merge fields such as {{firstname}} | \n
| replies | \nboolean | \nWhether replies are enabled for messages sent with this template | \n
| sender_id | \nstring | \nSender ID associated with the template | \n
| updated | \nstring | \nISO8601 timestamp, UTC | \n
| created | \nstring | \nISO8601 timestamp, UTC | \n
Only active templates are returned. Templates are read-only over the API, they are created and\nedited in the web interface.
\nTo send a message using a template, read the message field and pass it as the body when calling\nthe send endpoint. Merge fields are not substituted by this endpoint.
| Key | \nType | \nDescription | \nRequired | \nDefault | \n
|---|---|---|---|---|
| search | \nstring | \nSearch Term | \nNo | \n\n |
| sort_by | \nstring | \nSort field, one of `['id', 'firstname', 'lastname', 'created']` | \nNo | \nfirstname | \n
| sort_order | \nstring | \nSort order, one of `['asc', 'desc']` | \nNo | \n\n |
Create a new contact in, optionally specifying a group.
\n| Key | \nType | \nDescription | \nRequired | \nDefault | \n
|---|---|---|---|---|
| number | \nstring | \nMobile number of the Contact | \nYes | \n\n |
| firstname | \nstring | \nFirst Name of the Contact | \nNo | \n\n |
| surname | \nstring | \nLast Name of the Contact | \nNo | \n\n |
| string | \nEmail Address of the Contact | \nNo | \n\n | |
| group | \nstring | \nIf supplied, the new contact will be added to the group with the supplied title. If the group does not exist it will be created. | \nOptional | \n\n |
Update a contact.
\n| Key | \nType | \nDescription | \n
|---|---|---|
| id | \ninteger | \nContact's ID | \n
| Key | \nType | \nDescription | \nRequired | \nDefault | \n
|---|---|---|---|---|
| number | \nstring | \nMobile number of the Contact | \nYes | \n\n |
| firstname | \nstring | \nFirst Name of the Contact | \nNo | \n\n |
| surname | \nstring | \nLast Name of the Contact | \nNo | \n\n |
| string | \nEmail Address of the Contact | \nNo | \n\n | |
| group | \nstring | \nIf supplied, the new contact will be added to the group with the supplied title. If the group does not exist it will be created. | \nOptional | \n\n |
Show a contact.
\n| Key | \nType | \nDescription | \n
|---|---|---|
| id | \ninteger | \nContact's ID | \n
Delete a contact.
\n| Key | \nType | \nDescription | \n
|---|---|---|
| id | \ninteger | \nContact's ID | \n
Get a paginated list of all opt-outs for your account across all opt-out lists.
\nGET /api/v2/optouts\n| Parameter | \nType | \nDescription | \nRequired | \nDefault | \n
|---|---|---|---|---|
| search | \nstring | \nSearch for partial or whole number | \nNo | \n\n |
| page | \ninteger | \nPage number for pagination | \nNo | \n1 | \n
Returns a paginated list of opt-out objects.
\n{\n \"data\": [\n {\n \"id\": 12345,\n \"user\": 1,\n \"number\": \"+61412345678\",\n \"method\": \"SMS\",\n \"opt_out_list\": {\n \"id\": 1,\n \"name\": \"Default Opt-Out List\",\n \"is_default\": true\n },\n \"updated\": \"2021-02-17 22:52:07\",\n \"created\": \"2021-02-17 22:52:07\"\n },\n {\n \"id\": 12346,\n \"user\": 1,\n \"number\": \"+61412345679\",\n \"method\": \"API\",\n \"opt_out_list\": {\n \"id\": 2,\n \"name\": \"Marketing Opt-Outs\",\n \"is_default\": false\n },\n \"updated\": \"2021-02-18 10:30:15\",\n \"created\": \"2021-02-18 10:30:15\"\n }\n ],\n \"links\": {\n \"first\": \"http://example.com/api/v2/optouts?page=1\",\n \"last\": \"http://example.com/api/v2/optouts?page=5\",\n \"prev\": null,\n \"next\": \"http://example.com/api/v2/optouts?page=2\"\n },\n \"meta\": {\n \"current_page\": 1,\n \"from\": 1,\n \"last_page\": 5,\n \"per_page\": 100,\n \"to\": 100,\n \"total\": 489\n }\n}\n| Field | \nType | \nDescription | \n
|---|---|---|
| id | \ninteger | \nUnique identifier for the opt-out record | \n
| user | \ninteger | \nID of the user who owns this opt-out | \n
| number | \nstring | \nThe phone number that opted out (E164 format) | \n
| method | \nstring | \nHow the opt-out was created (SMS, API, MANUAL, etc.) | \n
| opt_out_list | \nobject | \nDetails of the opt-out list this opt-out belongs to | \n
| opt_out_list.id | \ninteger | \nID of the opt-out list | \n
| opt_out_list.name | \nstring | \nName of the opt-out list | \n
| opt_out_list.is_default | \nboolean | \nWhether this is the default opt-out list | \n
| updated | \ndatetime | \nWhen the opt-out was last updated | \n
| created | \ndatetime | \nWhen the opt-out was created | \n
Create a new opt out. Messages will no longer be sent to the number.
\n| Key | \nType | \nDescription | \nRequired | \nDefault | \n
|---|---|---|---|---|
| number | \nstring | \nMobile number of the Optout. If the number already exists, no new optout will be created | \nYes | \n\n |
| opt_out_list_id | \ninteger | \nID of the opt-out list to add the number to. Must belong to the authenticated user. Cannot be used with opt_out_list_name. | \nNo | \nUser's default list | \n
| opt_out_list_name | \nstring | \nName of the opt-out list to add the number to. If the list doesn't exist, it will be created. Cannot be used with opt_out_list_id. | \nNo | \nUser's default list | \n
opt_out_list_id nor opt_out_list_name is provided, the opt-out will be added to the user's default list.opt_out_list_name, the list will be created automatically if it doesn't exist.Show a optout.
\n| Key | \nType | \nDescription | \n
|---|---|---|
| id | \ninteger | \nOptout's ID | \n
Delete an optout. Use the index endpoint to search for the number you wish to remove, then delete using this endpoint.
| Key | \nType | \nDescription | \n
|---|---|---|
| id | \ninteger | \nOptout's ID | \n
Get a list of all opt-out lists for your account. Opt-out lists allow you to organize and manage different groups of opted-out recipients for different campaigns or purposes.
\nGET /api/v2/optout-lists\nReturns an array of opt-out list objects, ordered by default lists first, then alphabetically by name.
\nNote: Each account has at least one default opt-out list that is automatically created.
\n{\n \"data\": [\n {\n \"id\": 1,\n \"name\": \"Default Opt-Out List\",\n \"is_default\": true,\n \"opt_out_count\": 245,\n \"created_at\": \"2021-02-17T22:52:07Z\",\n \"updated_at\": \"2021-02-17T22:52:07Z\"\n },\n {\n \"id\": 2,\n \"name\": \"Marketing Opt-Outs\",\n \"is_default\": false,\n \"opt_out_count\": 89,\n \"created_at\": \"2021-03-10T14:30:22Z\",\n \"updated_at\": \"2021-03-15T09:45:18Z\"\n }\n ]\n}\n| Field | \nType | \nDescription | \n
|---|---|---|
| id | \ninteger | \nUnique identifier for the opt-out list | \n
| name | \nstring | \nName of the opt-out list | \n
| is_default | \nboolean | \nWhether this is the default opt-out list for the account | \n
| opt_out_count | \ninteger | \nNumber of opt-outs in this list | \n
| created_at | \ndatetime | \nWhen the opt-out list was created (ISO8601 format) | \n
| updated_at | \ndatetime | \nWhen the opt-out list was last updated (ISO8601 format) | \n
Get details of a specific opt-out list. This endpoint provides information about the opt-out list including its name, default status, and the number of opt-outs it contains.
\nGET /api/v2/optout-lists/{id}\n| Parameter | \nType | \nDescription | \nRequired | \n
|---|---|---|---|
| id | \ninteger | \nThe ID of the opt-out list to retrieve | \nYes | \n
Returns a single opt-out list object.
\n{\n \"data\": {\n \"id\": 1,\n \"name\": \"Marketing Opt-Outs\",\n \"is_default\": false,\n \"opt_out_count\": 89,\n \"created_at\": \"2021-03-10T14:30:22Z\",\n \"updated_at\": \"2021-03-15T09:45:18Z\"\n }\n}\n| Field | \nType | \nDescription | \n
|---|---|---|
| id | \ninteger | \nUnique identifier for the opt-out list | \n
| name | \nstring | \nName of the opt-out list | \n
| is_default | \nboolean | \nWhether this is the default opt-out list for the account | \n
| opt_out_count | \ninteger | \nNumber of opt-outs in this list | \n
| created_at | \ndatetime | \nWhen the opt-out list was created (ISO8601 format) | \n
| updated_at | \ndatetime | \nWhen the opt-out list was last updated (ISO8601 format) | \n
If the opt-out list doesn't exist or doesn't belong to your account:
\n{\n \"message\": \"No query results for model [App\\\\Models\\\\OptOutList] {id}\"\n}\nGet all opt-outs that belong to a specific opt-out list.
\nGET /api/v2/optout-lists/{id}/optouts\n| Parameter | \nType | \nDescription | \nRequired | \n
|---|---|---|---|
| id | \ninteger | \nThe ID of the opt-out list | \nYes | \n
| Parameter | \nType | \nDescription | \nRequired | \nDefault | \n
|---|---|---|---|---|
| search | \nstring | \nSearch for partial or whole number, first name, or last name | \nNo | \n\n |
| page | \ninteger | \nPage number for pagination | \nNo | \n1 | \n
Returns a paginated list of opt-out objects that belong to the specified opt-out list.
\n{\n \"data\": [\n {\n \"id\": 12345,\n \"user\": 1,\n \"number\": \"+61412345678\",\n \"method\": \"SMS\",\n \"opt_out_list\": {\n \"id\": 1,\n \"name\": \"Marketing Opt-Outs\",\n \"is_default\": false\n },\n \"updated\": \"2021-02-17 22:52:07\",\n \"created\": \"2021-02-17 22:52:07\"\n },\n {\n \"id\": 12346,\n \"user\": 1,\n \"number\": \"+61412345679\",\n \"method\": \"API\",\n \"opt_out_list\": {\n \"id\": 1,\n \"name\": \"Marketing Opt-Outs\",\n \"is_default\": false\n },\n \"updated\": \"2021-02-18 10:30:15\",\n \"created\": \"2021-02-18 10:30:15\"\n }\n ],\n \"links\": {\n \"first\": \"http://example.com/api/v2/optout-lists/1/optouts?page=1\",\n \"last\": \"http://example.com/api/v2/optout-lists/1/optouts?page=3\",\n \"prev\": null,\n \"next\": \"http://example.com/api/v2/optout-lists/1/optouts?page=2\"\n },\n \"meta\": {\n \"current_page\": 1,\n \"from\": 1,\n \"last_page\": 3,\n \"path\": \"http://example.com/api/v2/optout-lists/1/optouts\",\n \"per_page\": 50,\n \"to\": 50,\n \"total\": 142\n }\n}\n| Field | \nType | \nDescription | \n
|---|---|---|
| id | \ninteger | \nUnique identifier for the opt-out record | \n
| user | \ninteger | \nID of the user who owns this opt-out | \n
| number | \nstring | \nThe phone number that opted out (E164 format) | \n
| method | \nstring | \nHow the opt-out was created (SMS, API, MANUAL, etc.) | \n
| updated | \ndatetime | \nWhen the opt-out was last updated | \n
| created | \ndatetime | \nWhen the opt-out was created | \n
If the opt-out list doesn't exist or doesn't belong to your account:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","name":"touchSMS V2 Documentation","type":"collection"}},"urlObject":{"path":["v2","optout-lists","{{optout_list_id}}","optouts"],"host":["{{baseUrl}}"],"query":[],"variable":[]}},"response":[{"id":"4a4cac76-d4c4-4f20-a21a-ed7053ffb669","name":"Show Opt out List","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"}],"url":"{{baseUrl}}/v2/optout-lists/{{optout_list_id}}/optouts"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.21.1"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept-Encoding"},{"key":"X-Powered-By","value":"PHP/7.4.22"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Thu, 30 Sep 2021 01:13:33 GMT"},{"key":"X-RateLimit-Limit","value":"240"},{"key":"X-RateLimit-Remaining","value":"239"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Content-Encoding","value":"gzip"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"id\": 12345,\n \"user\": 1,\n \"number\": \"+61412345678\",\n \"method\": \"SMS\",\n \"opt_out_list\": {\n \"id\": 1,\n \"name\": \"Marketing Opt-Outs\",\n \"is_default\": false\n },\n \"updated\": \"2021-02-17 22:52:07\",\n \"created\": \"2021-02-17 22:52:07\"\n },\n {\n \"id\": 12346,\n \"user\": 1,\n \"number\": \"+61412345679\",\n \"method\": \"API\",\n \"opt_out_list\": {\n \"id\": 1,\n \"name\": \"Marketing Opt-Outs\",\n \"is_default\": false\n },\n \"updated\": \"2021-02-18 10:30:15\",\n \"created\": \"2021-02-18 10:30:15\"\n }\n ],\n \"links\": {\n \"first\": \"https://{{baseUrl}}/v2/optout-lists/1/optouts?page=1\",\n \"last\": \"https://{{baseUrl}}/v2/optout-lists/1/optouts?page=3\",\n \"prev\": null,\n \"next\": \"https://{{baseUrl}}/v2/optout-lists/1/optouts?page=2\"\n },\n \"meta\": {\n \"current_page\": 1,\n \"from\": 1,\n \"last_page\": 3,\n \"path\": \"https://{{baseUrl}}/v2/optout-lists/1/optouts\",\n \"per_page\": 50,\n \"to\": 50,\n \"total\": 142\n }\n }\n"}],"_postman_id":"25aeb3d3-f8e6-4b35-bb14-87ea56d6a477"}],"id":"e418e4bf-cc9c-40a7-96e1-42193bd307e3","_postman_id":"e418e4bf-cc9c-40a7-96e1-42193bd307e3","description":"","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","name":"touchSMS V2 Documentation","type":"collection"}}},{"name":"Account","item":[{"name":"Get Account","id":"4691ee61-96fe-4d61-99a7-b39b429d37da","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"{{baseUrl}}/v2/account","description":"Use this method to retrieve your account information. It will return your credit count, default sender ID & username.\nThis endpoint can also be used to test that you are correctly authenticated without sending an SMS.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","name":"touchSMS V2 Documentation","type":"collection"}},"urlObject":{"path":["v2","account"],"host":["{{baseUrl}}"],"query":[],"variable":[]}},"response":[{"id":"c3091ddd-8623-4b2b-afc4-9e97c4aac557","name":"Get Account","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"{{baseUrl}}/v2/account"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"id\": 1,\n \"firstname\": \"test\",\n \"surname\": \"test\",\n \"email\": \"test@test.com\",\n \"mobile\": \"61412345678\",\n \"credits\": 24446,\n \"settings\": {\n \"timezone\": \"Australia/Sydney\",\n \"allow_contact_duplicates\": false,\n \"allow_sms_duplicates\": false\n }\n }\n}"}],"_postman_id":"4691ee61-96fe-4d61-99a7-b39b429d37da"},{"name":"Get Sender Ids","id":"f794f247-e4fc-4bf0-82ec-70987edfb9c4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"application/json"}],"url":"{{baseUrl}}/v2/account/sender-ids","description":"Use this method to retrieve the allowed sender IDs for your account. You must send from a verified sender id.
\nPlease visit the Sender Id Management to add a new sender id.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","name":"touchSMS V2 Documentation","type":"collection"}},"urlObject":{"path":["v2","account","sender-ids"],"host":["{{baseUrl}}"],"query":[],"variable":[]}},"response":[{"id":"211f4e9c-31db-4d5d-8cf7-141da21ded7c","name":"Get Account","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"}],"url":"{{baseUrl}}/v2/account/sender-ids"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"type\": \"shared\",\n \"type_description\": \"Shared\",\n \"sender_id\": \"SHARED_NUMBER\",\n \"label\": \"Shared Local Number\",\n \"enabled\": true,\n \"default\": false\n },\n {\n \"type\": \"dedicated\",\n \"type_description\": \"Dedicated\",\n \"sender_id\": \"61412345678\",\n \"label\": \"61412345678 (Virtual Number)\",\n \"enabled\": true,\n \"default\": true\n },\n {\n \"type\": \"own\",\n \"type_description\": \"Own\",\n \"sender_id\": \"61412345678\",\n \"label\": \"61412345678\",\n \"enabled\": true,\n \"default\": false\n },\n {\n \"type\": \"custom\",\n \"type_description\": \"Custom\",\n \"sender_id\": \"TESTDEV\",\n \"label\": \"TESTDEV\",\n \"enabled\": true,\n \"default\": false\n }\n ]\n}"}],"_postman_id":"f794f247-e4fc-4bf0-82ec-70987edfb9c4"}],"id":"d8628b40-b09c-426d-9f0e-07e5f1a12fd0","_postman_id":"d8628b40-b09c-426d-9f0e-07e5f1a12fd0","description":"","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","name":"touchSMS V2 Documentation","type":"collection"}}},{"name":"Inbounds","item":[{"name":"List / Poll Inbounds","id":"ca37baf9-d6fb-47c1-bae7-0813697c1649","protocolProfileBehavior":{"disabledSystemHeaders":{},"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"{{baseUrl}}/v2/inbounds","description":"If you wish to receive incoming messages, it is strongly recommended that you use webhooks. Please see the \"Webhooks / Callbacks\" section in the sidebar.
\nIf your system cannot receive webhooks, or you prefer to poll for inbound you can use this endpoint. By passing a time or id, the system will only return inbounds newer than specified.
\nPlease note, this endpoint is rate limited to 120 requests per hour. For real time notifications, use webhooks.
\n| Key | \nType | \nDescription | \nRequired | \nDefault | \n
|---|---|---|---|---|
| created_after | \nstring | \nISO8061 date/time. Only messages newer than this timestamp will be returned | \nNo | \n\n |
| id_after | \ninteger | \nReturn only messages newer than a specific inbound ID. Query the API and keep a reference to the last ID seen, passing it to this param to only receive new messages. | \nNo | \n\n |
Inbound MMS media is returned on the media_urls field, as a flat array of direct URLs to each media\nfile. For a plain SMS the field is empty.
{\n \"id\": 123456,\n \"content\": \"Here are the photos\",\n \"number\": \"61412345678\",\n \"media_urls\": [\n \"https://mms.touchsms.com.au/m/01gw171s65ecm8mhpx2086f7pg.jpeg\",\n \"https://mms.touchsms.com.au/m/01gw171s65ecm8mhpx2086f7ph.jpeg\"\n ]\n}\nThese URLs require no authentication to download. See \"Inbound MMS Media\" in the \"Webhooks /\nCallbacks\" section for details on downloading, retention, and handling multiple media files. Note\nthat the message_received webhook returns the same media as a media array of\n{\"key\": ..., \"url\": ...} objects rather than as flat strings.
Create a new verification.
\n| Key | \nType | \nDescription | \nRequired | \nDefault | \n
|---|---|---|---|---|
| destination | \nstring | \nMobile number to send verification to. E164 format preferred, API will attempt to parse other formats. | \nYes | \n\n |
| source | \nstring | \nSenderID / Source of verification SMS. Note, the sender must be added on your account as a verified sender ID. | \nNo | \nAccount Default Sender | \n
| template | \nstring | \nMessage template (content). Must contain `%code%`, may be up to 300 characters. | \nNo | \nYour verification code is %code% | \n
| metadata | \nobject | \nAttach metadata to the verification. For example, you could pass the action the user was attempting. See section below on validation of metadata. | \nNo | \n\n |
| expiry_seconds | \ninteger | \nHow long the verification will be usable for. Once expired, a verification cannot be used | \nNo | \n300 | \n
| token_length | \ninteger | \nLength of the generated code. Defaults to 6 characters. | \nNo | \n6 | \n
You can supply up to 10 key/value pairs as metadata with each message, allowing your integration to identify and associate delivery receipt and inbound replies with entities in your system.
\nEach key may be up to 50 characters and must be a string. Each value may be up to 100 characters and may be a string or an integer.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","name":"touchSMS V2 Documentation","type":"collection"}},"urlObject":{"path":["v3","verify"],"host":["{{baseUrl}}"],"query":[],"variable":[]}},"response":[{"id":"e24728b5-89e4-4883-9e37-a4f2fbf797b5","name":"Create Verification","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"destination\": \"0412345678\",\n \"template\": \"Your verification code is %code%\"\n}","options":{"raw":{"language":"json"}}},"url":"{{baseUrl}}/v3/verify"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"id\": \"cb4d9527-1d3a-4def-85ba-f1fec9489c4f\",\n \"status\": \"sent\",\n \"type\": \"sms\",\n \"destination\": \"61412345678\",\n \"source\": \"61491570159\",\n \"metadata\": null,\n \"template\": \"Your verification code is %code%\",\n \"expires_at\": \"2023-02-11T07:57:08.000000Z\",\n \"created_at\": \"2023-02-11T07:52:08.000000Z\"\n }\n}"}],"_postman_id":"2a61f2ce-0ded-4131-9300-f50c6e7df2df"},{"name":"Check Verification","id":"a16828a1-61b6-480a-94b1-74cf46ce7338","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"{{baseUrl}}/v3/verify/{{verify_id}}/verify","description":"Check a new verification.
\n| Key | \nType | \nDescription | \nRequired | \nDefault | \n
|---|---|---|---|---|
| code | \nstring | \nCode submitted by the user. | \nYes | \n\n |
The API will return the verification, along with some details indicating if it failed or passed.
\nYou can use the verify_success key to determine if the verification succeeded.
If there is an error, it will be in the verify_error key, and explain why the verification failed.
{\n \"data\": {\n \"id\": \"cb4d9527-1d3a-4def-85ba-f1fec9489c4f\",\n \"status\": \"verified\",\n ...\n },\n \"verify_success\": true,\n \"verify_error\": null\n}\n{\n \"data\": {\n \"id\": \"cb4d9527-1d3a-4def-85ba-f1fec9489c4f\",\n \"status\": \"sent\",\n ...\n },\n \"verify_success\": false,\n \"verify_error\": \"Provided code does not match verify\"\n}\nCheck a new verification by destination number.
\nNote: It is recommended to check verifications by their ID, not by destination number. If you use this endpoint, ensure two users cannot use the same number at the same time, and that the user does not change the verification number throughout the process in your app.
\n| Key | \nType | \nDescription | \nRequired | \nDefault | \n
|---|---|---|---|---|
| destination | \nstring | \nMobile number being verified. | \nYes | \n\n |
| code | \nstring | \nCode submitted by the user. | \nYes | \n\n |
Please see the documentation for the \"Check Verification\" request. This endpoint returns the same response.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","name":"touchSMS V2 Documentation","type":"collection"}},"urlObject":{"path":["v3","verify","verify-by"],"host":["{{baseUrl}}"],"query":[],"variable":[]}},"response":[{"id":"d916b9c1-6036-42f6-9f2f-011412dcf4e2","name":"Check Verification - Success","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"destination\": \"61412345678\",\n \"code\": \"123456\"\n}","options":{"raw":{"language":"json"}}},"url":"{{baseUrl}}/v3/verify/verify-by"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"id\": \"cb4d9527-1d3a-4def-85ba-f1fec9489c4f\",\n \"status\": \"verified\",\n \"type\": \"sms\",\n \"destination\": \"61412345678\",\n \"source\": \"61491570159\",\n \"metadata\": null,\n \"template\": \"Your verification code is %code%\",\n \"expires_at\": \"2023-02-11T07:57:08.000000Z\",\n \"created_at\": \"2023-02-11T07:52:08.000000Z\"\n },\n \"verify_success\": true,\n \"verify_error\": null\n}"},{"id":"70c4c979-66fe-4e15-943e-32d746d22e76","name":"Check Verification - Failure","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"destination\": \"61412345678\",\n \"code\": \"123456\"\n}","options":{"raw":{"language":"json"}}},"url":"{{baseUrl}}/v3/verify/verify-by"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"id\": \"cb4d9527-1d3a-4def-85ba-f1fec9489c4f\",\n \"status\": \"verified\",\n \"type\": \"sms\",\n \"destination\": \"61412345678\",\n \"source\": \"61491570159\",\n \"metadata\": null,\n \"template\": \"Your verification code is %code%\",\n \"expires_at\": \"2023-02-11T07:57:08.000000Z\",\n \"created_at\": \"2023-02-11T07:52:08.000000Z\"\n },\n \"verify_success\": false,\n \"verify_error\": \"Provided code does not match verify\"\n}"}],"_postman_id":"d2614982-9294-42a9-8ad7-70eeb8f3f707"},{"name":"Cancel Verification","id":"ebebfa3f-0d13-421f-ba4a-3a7d9ea14769","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"application/json"}],"url":"{{baseUrl}}/v3/verify/{{verify_id}}/cancel","description":"Cancel a verification. Once cancelled, it cannot be verified.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","name":"touchSMS V2 Documentation","type":"collection"}},"urlObject":{"path":["v3","verify","{{verify_id}}","cancel"],"host":["{{baseUrl}}"],"query":[],"variable":[]}},"response":[{"id":"fe7dd738-8b80-4e31-9ef2-bc12bca8a7a0","name":"Cancel Verification","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"application/json"}],"url":"{{baseUrl}}/v3/verify/{{verify_id}}/cancel"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"id\": \"cb4d9527-1d3a-4def-85ba-f1fec9489c4f\",\n \"status\": \"cancelled\",\n \"type\": \"sms\",\n \"destination\": \"61412345678\",\n \"source\": \"61491570159\",\n \"metadata\": null,\n \"template\": \"Your verification code is %code%\",\n \"expires_at\": \"2023-02-11T07:57:08.000000Z\",\n \"created_at\": \"2023-02-11T07:52:08.000000Z\"\n }\n}"}],"_postman_id":"ebebfa3f-0d13-421f-ba4a-3a7d9ea14769"},{"name":"Cancel Verification By Destination","id":"e3056cb9-d39f-457d-8da1-c50cd3b7a8db","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"application/json"}],"url":"{{baseUrl}}/v3/verify/cancel-by","description":"Cancel all verifications by destination
\n| Key | \nType | \nDescription | \nRequired | \nDefault | \n
|---|---|---|---|---|
| destination | \nstring | \nMobile number being verified. | \nYes | \n\n |
Our SMS Verification API is a highly scalable, secure, and reliable solution for verifying user's mobile number during sign up and account creation processes.
\nSave hundreds of hours of developer time by integrating our purpose build verification API.
\nTo verify a user, first you must create a verify request. touchSMS will then send a code via SMS to the supplied destination, and returns an ID to you. Once the user receives the SMS, your application sends that code to us, and we verify the number.
\n/api/v3/verify - Verification is created, and returned. Persist the returned id (uuid) for the next step./api/v3/verify/{verify_id}/verify - Submit the code and received the results of the validation/api/v3/verify/verify-by - Submit destination number and code, and receive the results of the validationSee the associated methods in the sidebar under \"Verify\"
\n","_postman_id":"e07e2b76-36d4-45fd-8b68-b18bb755df32","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{token}}"}]},"isInherited":true,"source":{"_postman_id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","id":"b4a7aebb-82c0-4c3a-98a2-e7faad56978e","name":"touchSMS V2 Documentation","type":"collection"}}},{"name":"Webhook Subscriptions","item":[{"name":"List Webhook Subscriptions","id":"95328ec0-20e4-4a9f-910a-297b2e319fbe","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"application/json"}],"url":"{{baseUrl}}/v2/webhook-subscriptions","description":"Webhook subscriptions can be managed through the API as well as through the web interface. See the\n\"Webhooks / Callbacks\" section for the payloads each event sends and for signature verification.
\nGET /v2/webhook-subscriptions\nReturns the webhook subscriptions on your account, newest first. Paginated, 25 per page.
\n{\n \"data\": [\n {\n \"id\": 123,\n \"status\": \"Active\",\n \"event\": \"message_received\",\n \"name\": \"Inbound to CRM\",\n \"url\": \"https://example.com/hooks/inbound\",\n \"request_method\": \"POST\",\n \"request_encoding_type\": \"json\",\n \"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"}\n ],\n \"created_at\": \"2024-02-02T23:51:19Z\",\n \"updated_at\": \"2024-03-11T02:14:07Z\"\n }\n ],\n \"links\": {},\n \"meta\": {}\n}\nActive The subscription is enabled and receiving events.Disabled The subscription has been disabled manually.Disabled Failing The subscription was disabled automatically after repeated delivery failures.A subscription in Disabled Failing will not receive events until it is re-enabled. If your endpoint\nwas down, check for this state once it is back up.
POST /v2/webhook-subscriptions\n{\n \"name\": \"Inbound to CRM\",\n \"event\": \"message_received\",\n \"url\": \"https://example.com/hooks/inbound\",\n \"request_method\": \"POST\",\n \"request_encoding_type\": \"json\",\n \"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"}\n ]\n}\nReturns 201 with the created subscription.
| Key | \nType | \nDescription | \nRequired | \n
|---|---|---|---|
| name | \nstring | \nA name for the subscription. Shown in the web interface. | \nYes | \n
| event | \nstring | \nThe event to subscribe to. One of message_received, message_dlr, optout_created, message_received_3cx. | \n Yes | \n
| url | \nstring | \nThe URL to send the webhook to. Must be a valid URL, and cannot point at a `touchSMS` owned domain. | \nYes | \n
| request_method | \nstring | \nPOST or GET. | \n Yes | \n
| request_encoding_type | \nstring | \njson or form. Required when request_method is POST. | \n Conditional | \n
| headers | \narray | \nCustom headers to send with the webhook. Must be present, send an empty array if you do not need any. Maximum 10. | \nYes | \n
headers is an array of objects, each with a key and a value, rather than a plain object:
\"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"},\n {\"key\": \"X-Source\", \"value\": \"touchsms\"}\n]\nThe key must be a valid HTTP header name, between 3 and 50 characters. The value must be between 3\nand 200 characters. Up to 10 headers are allowed.
\nNote that headers is required even when empty. Send \"headers\": [] if you have none.
PUT /v2/webhook-subscriptions/{id}\nTakes the same body as create. All fields are required, so send the full object rather than only the\nfields you are changing.
\nDELETE /v2/webhook-subscriptions/{id}\nReturns 204 No Content.
Webhook subscriptions can be managed through the API as well as through the web interface. See the\n\"Webhooks / Callbacks\" section for the payloads each event sends and for signature verification.
\nGET /v2/webhook-subscriptions\nReturns the webhook subscriptions on your account, newest first. Paginated, 25 per page.
\n{\n \"data\": [\n {\n \"id\": 123,\n \"status\": \"Active\",\n \"event\": \"message_received\",\n \"name\": \"Inbound to CRM\",\n \"url\": \"https://example.com/hooks/inbound\",\n \"request_method\": \"POST\",\n \"request_encoding_type\": \"json\",\n \"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"}\n ],\n \"created_at\": \"2024-02-02T23:51:19Z\",\n \"updated_at\": \"2024-03-11T02:14:07Z\"\n }\n ],\n \"links\": {},\n \"meta\": {}\n}\nActive The subscription is enabled and receiving events.Disabled The subscription has been disabled manually.Disabled Failing The subscription was disabled automatically after repeated delivery failures.A subscription in Disabled Failing will not receive events until it is re-enabled. If your endpoint\nwas down, check for this state once it is back up.
POST /v2/webhook-subscriptions\n{\n \"name\": \"Inbound to CRM\",\n \"event\": \"message_received\",\n \"url\": \"https://example.com/hooks/inbound\",\n \"request_method\": \"POST\",\n \"request_encoding_type\": \"json\",\n \"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"}\n ]\n}\nReturns 201 with the created subscription.
| Key | \nType | \nDescription | \nRequired | \n
|---|---|---|---|
| name | \nstring | \nA name for the subscription. Shown in the web interface. | \nYes | \n
| event | \nstring | \nThe event to subscribe to. One of message_received, message_dlr, optout_created, message_received_3cx. | \n Yes | \n
| url | \nstring | \nThe URL to send the webhook to. Must be a valid URL, and cannot point at a `touchSMS` owned domain. | \nYes | \n
| request_method | \nstring | \nPOST or GET. | \n Yes | \n
| request_encoding_type | \nstring | \njson or form. Required when request_method is POST. | \n Conditional | \n
| headers | \narray | \nCustom headers to send with the webhook. Must be present, send an empty array if you do not need any. Maximum 10. | \nYes | \n
headers is an array of objects, each with a key and a value, rather than a plain object:
\"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"},\n {\"key\": \"X-Source\", \"value\": \"touchsms\"}\n]\nThe key must be a valid HTTP header name, between 3 and 50 characters. The value must be between 3\nand 200 characters. Up to 10 headers are allowed.
\nNote that headers is required even when empty. Send \"headers\": [] if you have none.
PUT /v2/webhook-subscriptions/{id}\nTakes the same body as create. All fields are required, so send the full object rather than only the\nfields you are changing.
\nDELETE /v2/webhook-subscriptions/{id}\nReturns 204 No Content.
Webhook subscriptions can be managed through the API as well as through the web interface. See the\n\"Webhooks / Callbacks\" section for the payloads each event sends and for signature verification.
\nGET /v2/webhook-subscriptions\nReturns the webhook subscriptions on your account, newest first. Paginated, 25 per page.
\n{\n \"data\": [\n {\n \"id\": 123,\n \"status\": \"Active\",\n \"event\": \"message_received\",\n \"name\": \"Inbound to CRM\",\n \"url\": \"https://example.com/hooks/inbound\",\n \"request_method\": \"POST\",\n \"request_encoding_type\": \"json\",\n \"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"}\n ],\n \"created_at\": \"2024-02-02T23:51:19Z\",\n \"updated_at\": \"2024-03-11T02:14:07Z\"\n }\n ],\n \"links\": {},\n \"meta\": {}\n}\nActive The subscription is enabled and receiving events.Disabled The subscription has been disabled manually.Disabled Failing The subscription was disabled automatically after repeated delivery failures.A subscription in Disabled Failing will not receive events until it is re-enabled. If your endpoint\nwas down, check for this state once it is back up.
POST /v2/webhook-subscriptions\n{\n \"name\": \"Inbound to CRM\",\n \"event\": \"message_received\",\n \"url\": \"https://example.com/hooks/inbound\",\n \"request_method\": \"POST\",\n \"request_encoding_type\": \"json\",\n \"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"}\n ]\n}\nReturns 201 with the created subscription.
| Key | \nType | \nDescription | \nRequired | \n
|---|---|---|---|
| name | \nstring | \nA name for the subscription. Shown in the web interface. | \nYes | \n
| event | \nstring | \nThe event to subscribe to. One of message_received, message_dlr, optout_created, message_received_3cx. | \n Yes | \n
| url | \nstring | \nThe URL to send the webhook to. Must be a valid URL, and cannot point at a `touchSMS` owned domain. | \nYes | \n
| request_method | \nstring | \nPOST or GET. | \n Yes | \n
| request_encoding_type | \nstring | \njson or form. Required when request_method is POST. | \n Conditional | \n
| headers | \narray | \nCustom headers to send with the webhook. Must be present, send an empty array if you do not need any. Maximum 10. | \nYes | \n
headers is an array of objects, each with a key and a value, rather than a plain object:
\"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"},\n {\"key\": \"X-Source\", \"value\": \"touchsms\"}\n]\nThe key must be a valid HTTP header name, between 3 and 50 characters. The value must be between 3\nand 200 characters. Up to 10 headers are allowed.
\nNote that headers is required even when empty. Send \"headers\": [] if you have none.
PUT /v2/webhook-subscriptions/{id}\nTakes the same body as create. All fields are required, so send the full object rather than only the\nfields you are changing.
\nDELETE /v2/webhook-subscriptions/{id}\nReturns 204 No Content.
Webhook subscriptions can be managed through the API as well as through the web interface. See the\n\"Webhooks / Callbacks\" section for the payloads each event sends and for signature verification.
\nGET /v2/webhook-subscriptions\nReturns the webhook subscriptions on your account, newest first. Paginated, 25 per page.
\n{\n \"data\": [\n {\n \"id\": 123,\n \"status\": \"Active\",\n \"event\": \"message_received\",\n \"name\": \"Inbound to CRM\",\n \"url\": \"https://example.com/hooks/inbound\",\n \"request_method\": \"POST\",\n \"request_encoding_type\": \"json\",\n \"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"}\n ],\n \"created_at\": \"2024-02-02T23:51:19Z\",\n \"updated_at\": \"2024-03-11T02:14:07Z\"\n }\n ],\n \"links\": {},\n \"meta\": {}\n}\nActive The subscription is enabled and receiving events.Disabled The subscription has been disabled manually.Disabled Failing The subscription was disabled automatically after repeated delivery failures.A subscription in Disabled Failing will not receive events until it is re-enabled. If your endpoint\nwas down, check for this state once it is back up.
POST /v2/webhook-subscriptions\n{\n \"name\": \"Inbound to CRM\",\n \"event\": \"message_received\",\n \"url\": \"https://example.com/hooks/inbound\",\n \"request_method\": \"POST\",\n \"request_encoding_type\": \"json\",\n \"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"}\n ]\n}\nReturns 201 with the created subscription.
| Key | \nType | \nDescription | \nRequired | \n
|---|---|---|---|
| name | \nstring | \nA name for the subscription. Shown in the web interface. | \nYes | \n
| event | \nstring | \nThe event to subscribe to. One of message_received, message_dlr, optout_created, message_received_3cx. | \n Yes | \n
| url | \nstring | \nThe URL to send the webhook to. Must be a valid URL, and cannot point at a `touchSMS` owned domain. | \nYes | \n
| request_method | \nstring | \nPOST or GET. | \n Yes | \n
| request_encoding_type | \nstring | \njson or form. Required when request_method is POST. | \n Conditional | \n
| headers | \narray | \nCustom headers to send with the webhook. Must be present, send an empty array if you do not need any. Maximum 10. | \nYes | \n
headers is an array of objects, each with a key and a value, rather than a plain object:
\"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"},\n {\"key\": \"X-Source\", \"value\": \"touchsms\"}\n]\nThe key must be a valid HTTP header name, between 3 and 50 characters. The value must be between 3\nand 200 characters. Up to 10 headers are allowed.
\nNote that headers is required even when empty. Send \"headers\": [] if you have none.
PUT /v2/webhook-subscriptions/{id}\nTakes the same body as create. All fields are required, so send the full object rather than only the\nfields you are changing.
\nDELETE /v2/webhook-subscriptions/{id}\nReturns 204 No Content.
Webhook subscriptions can be managed through the API as well as through the web interface. See the\n\"Webhooks / Callbacks\" section for the payloads each event sends and for signature verification.
\nGET /v2/webhook-subscriptions\nReturns the webhook subscriptions on your account, newest first. Paginated, 25 per page.
\n{\n \"data\": [\n {\n \"id\": 123,\n \"status\": \"Active\",\n \"event\": \"message_received\",\n \"name\": \"Inbound to CRM\",\n \"url\": \"https://example.com/hooks/inbound\",\n \"request_method\": \"POST\",\n \"request_encoding_type\": \"json\",\n \"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"}\n ],\n \"created_at\": \"2024-02-02T23:51:19Z\",\n \"updated_at\": \"2024-03-11T02:14:07Z\"\n }\n ],\n \"links\": {},\n \"meta\": {}\n}\nActive The subscription is enabled and receiving events.Disabled The subscription has been disabled manually.Disabled Failing The subscription was disabled automatically after repeated delivery failures.A subscription in Disabled Failing will not receive events until it is re-enabled. If your endpoint\nwas down, check for this state once it is back up.
POST /v2/webhook-subscriptions\n{\n \"name\": \"Inbound to CRM\",\n \"event\": \"message_received\",\n \"url\": \"https://example.com/hooks/inbound\",\n \"request_method\": \"POST\",\n \"request_encoding_type\": \"json\",\n \"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"}\n ]\n}\nReturns 201 with the created subscription.
| Key | \nType | \nDescription | \nRequired | \n
|---|---|---|---|
| name | \nstring | \nA name for the subscription. Shown in the web interface. | \nYes | \n
| event | \nstring | \nThe event to subscribe to. One of message_received, message_dlr, optout_created, message_received_3cx. | \n Yes | \n
| url | \nstring | \nThe URL to send the webhook to. Must be a valid URL, and cannot point at a `touchSMS` owned domain. | \nYes | \n
| request_method | \nstring | \nPOST or GET. | \n Yes | \n
| request_encoding_type | \nstring | \njson or form. Required when request_method is POST. | \n Conditional | \n
| headers | \narray | \nCustom headers to send with the webhook. Must be present, send an empty array if you do not need any. Maximum 10. | \nYes | \n
headers is an array of objects, each with a key and a value, rather than a plain object:
\"headers\": [\n {\"key\": \"X-Api-Key\", \"value\": \"abc123\"},\n {\"key\": \"X-Source\", \"value\": \"touchsms\"}\n]\nThe key must be a valid HTTP header name, between 3 and 50 characters. The value must be between 3\nand 200 characters. Up to 10 headers are allowed.
\nNote that headers is required even when empty. Send \"headers\": [] if you have none.
PUT /v2/webhook-subscriptions/{id}\nTakes the same body as create. All fields are required, so send the full object rather than only the\nfields you are changing.
\nDELETE /v2/webhook-subscriptions/{id}\nReturns 204 No Content.
Webhooks are used to alert your application when events occur, such a receiving an inbound message or a delivery status change. In the touchSMS settings, you\ncan configure as many webhook subscriptions as required.
Open the webhook settings from the sidebar, by opening the settings submenu and clicking \"Webhooks\", or go to https://app.touchsms.com.au/settings/webhooks.
\nClick \"Create webhook subscription\" to create a new subscription, or edit an existing subscription.
\nYou can add custom headers, select the request method (GET or POST) and the encoding type (json or form).
message_receivedA webhook will be sent when an inbound message is received for your account (to a virtual number, or to a shared number).
\n{\n \"event\": \"message_received\", // Always message_received\n \"date\": \"2022-01-13T04:23:57Z\", // Date message was received\n \"id\": 123456, // Inbound message ID\n \"to\": \"SHARED_NUMBER\", // Number that received the message, either a dedicated number or \"SHARED_NUMBER\" for share numbers\n \"from\": \"61412345678\", // Number the message was received fro\n \"content\": \"Hello Reply\", // Message body\n \"media\": [ // Any media files, if the message was an MMS\n {\"key\": \"01gw171s65ecm8mhpx2086f7pg\", \"url\": \"https://mms.touchsms.com.au/m/01gw171s65ecm8mhpx2086f7pg.jpeg\"}\n ],\n \"is_opt_out\": false, // If the message resulted in an opt out\n \"in_reply_to_message\": { // Contains details of the message that the inbound is responding to. null if no outbound matched\n \"id\": 654321, // Outbound message ID\n \"content\": \"Hello World\", // Outbound message body\n \"metadata\": {\n \"your_system_id\": \"c5969b2c-d33a-402d-9d7e-f82c98f85be7\"\n }, // Outbound message metadata, supplied via API \n \"reference\": null, // Outbound message reference, supplied via API \n \"campaign_id\": 123456 // Outbound message campaign ID (used for reporting)\n }\n}\nWhen an inbound message is an MMS, the media array contains one entry per media file. For a plain\nSMS the array is present but empty ([]).
Each entry has two fields:
\nkey: the media file's unique identifier. Stable for the life of the file.url: a direct, fully qualified URL to the media file itself.The webhook does not embed the media file contents. Download the file from the url.
url is a direct link to the file and requires no authentication. No API key, no session, and no\nuser login. A server can fetch it unattended with a plain GET:
curl -O \"https://mms.touchsms.com.au/m/01gw171s65ecm8mhpx2086f7pg.jpeg\"\nBecause these URLs are unauthenticated, treat them as secrets: anyone who obtains a URL can retrieve\nthe file. Avoid forwarding them to untrusted recipients, and prefer attaching the downloaded file to\nany onward email rather than passing the link through.
\nThe file extension reflects the media type as received from the carrier (commonly .jpeg, .png,\nor .gif). Do not assume a particular type. Read the Content-Type response header when\nprocessing the download.
An MMS may contain several media files. The media array is ordered as received from the carrier and\nis not limited to a single entry, so always iterate it rather than reading media[0].
{\n \"event\": \"message_received\",\n \"date\": \"2022-01-13T04:23:57Z\",\n \"id\": 123456,\n \"to\": \"SHARED_NUMBER\",\n \"from\": \"61412345678\",\n \"content\": \"Here are the photos\", // Any text sent alongside the media. Empty string if the MMS had no text\n \"media\": [\n {\"key\": \"01gw171s65ecm8mhpx2086f7pg\", \"url\": \"https://mms.touchsms.com.au/m/01gw171s65ecm8mhpx2086f7pg.jpeg\"},\n {\"key\": \"01gw171s65ecm8mhpx2086f7ph\", \"url\": \"https://mms.touchsms.com.au/m/01gw171s65ecm8mhpx2086f7ph.jpeg\"},\n {\"key\": \"01gw171s65ecm8mhpx2086f7pj\", \"url\": \"https://mms.touchsms.com.au/m/01gw171s65ecm8mhpx2086f7pj.png\"}\n ],\n \"is_opt_out\": false,\n \"in_reply_to_message\": null\n}\nDownload media as soon as you receive the webhook, and store your own copy. Media files are\nretained according to the storage retention policy for your account, and the url is not guaranteed\nto remain resolvable indefinitely. Treat the URL as a means of collecting the file once, not as\nlong-term storage you can fetch from on demand.
If a download fails, retry it promptly rather than deferring. Your webhook endpoint should not\nreturn a success response until the media is safely stored.
\nmessage_dlrA webhook will be sent each time the delivery status for any messages you send changes.
\n{\n \"event\": \"message_dlr\", // Always message_dlr\n \"date\": \"2022-06-06T10:35:45Z\", // Date status changed\n \"id\": 123456, // Outbound message ID\n \"to\": \"61411802860\", // Destination number of the message\n \"from\": \"61419046139\", // Number the message was sent from, \"SHARED_NUMBER\" for share numbers\n \"content\": \"Test\", // Outbound message body\n \"metadata\": {\n \"your_system_id\": \"c5969b2c-d33a-402d-9d7e-f82c98f85be7\"\n },\n \"reference\": null, // Outbound message reference, supplied via API \n \"campaign_id\": 618, // Outbound message campaign ID (used for reporting)\n \"status\": \"delivered\" // New message status (see below)\n}\nAny status beginning with failed should be considered a delivery failure.
delivered Message was delivered to the user (in some cases, to the user's carrier)failed Generic failed statusfailed_rejected Carrier rejected the messagefailed_expired Message could not be delivered to the user before it expiredfailed_insufficient_balance Account balance too low to send message. (not billed)cancelled Message sent to testing numbers. (not billed)filtered Message blocked by spam filters (including upstream).filtered_duplicate Message filtered as it was detected as duplicate (not billed)optout_createdA webhook will be sent each time an opt-out is created on your account (either via the UI, API, opt out link or opt out sms reply). Note that imported opt-outs do not trigger webhooks.
\n{\n \"event\": \"optout_created\", // Always optout_created\n \"id\": 123456, // Optout ID\n \"number\": \"61419046139\", // Number that was opted out\n \"method\": \"SMS\", // How the opt-out was created (SMS, API, MANUAL, etc.)\n \"country\": {\n \"id\": 1, // Country Id\n \"iso\": \"AU\", // ISO 2 Letter Country Code\n \"name\": \"Australia\" // Country Name\n },\n \"opt_out_list\": {\n \"id\": 1, // Opt-out list ID\n \"name\": \"Default Opt-Out List\", // Opt-out list name\n \"is_default\": true // Whether this is the default opt-out list\n },\n \"created\": \"2022-06-06T10:35:45Z\" // Date opt out was created\n}\nThe method field indicates how the opt-out was created:
SMS - Opt-out created via SMS reply (e.g., replying \"STOP\")API - Opt-out created via API endpointMANUAL - Opt-out created manually through the web interfaceIMPORT - Opt-out created via import (note: imports do not trigger webhooks)LINK - Opt-out created via opt-out linkWebhooks will be retired up to 15 times, with exponentially increasing delays capped at 12 hours.\ntouchSMS will continue to retry until your service responds with a 2xx code.
Webhooks sent for your account will be signed with the webhook secret, which is available in your API Settings.
\nThe algorithm used is HMAC-SHA256(raw_json_request_body)
For example, to verify the webhook authenticity in PHP:
hash_hmac('sha256', $payloadJson, 'my-webhook-secret');\nDocumentation provided below for historical purposes. New implementations should use \"Webhook Subscriptions\"
\nDelivery Receipts or DLRs, are notifications received from the carrier relating to the success and statuses of an attempted SMS Delivery.
They are delivered as a POST request, with the following body params:
| Parameter | \nDescription | \n
|---|---|
| reference | \nYour reference code provided when submitting the message over the RESTful API. | \n
| description | \nThe delivery status of your message, this can be one of two options\n
| \n
| time | \nThe time that the receipt was generated, will be in the format of;\n YYYY-MM-DD HH:MM:SS | \n
| timezone | \nThe timezone of the of the timestamp provided, the timezone is always set to your account timezone for ease of use. | \n
Incoming SMS are similar to DLRs, except that they contain an incoming message instead of a message status.
\nThey are delivered as a POST request, with the following body params:
| Parameter | \nDescription | \n
|---|---|
| reference | \nYour reference code provided when submitting the message over the RESTful API. | \n
| message | \nThe message that was sent as a reply | \n
| number | \nThe mobile number that sent the reply (International format) | \n
| time | \nThe time that the receipt was generated, will be in the format of;\n YYYY-MM-DD HH:MM:SS | \n
| timezone | \nThe timezone of the of the timestamp provided, the timezone is always set to your account timezone for ease. | \n