{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"586a2d10-243f-4c77-afa1-ea727c468065","name":"touchSMS Legacy Api Documentation","description":"# Legacy Documentation\n## Please note these are the API docs for our legacy API. All new integration should use our V2 API.\n\nV2 Postman Documentation.\n\n\n\n\n\n\n\n\n\n\n\n## Getting Started\n\nWant 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.\n\nYou can run the examples for each request by expanding them in the top right.\n\n

\"Examples\"

\n\n----\n\n## Base URL\n\n https://platform.touchsms.com.au/rest\n\n----\n\n# Authentication\n\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.\n\nClick 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 a Token Id and a\nToken Secret.\n\nWhen making requests to the API, credentials are passed using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).\n\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.\n\n

\"Basic

\n\nFor security purposes, all requests to our API must be made over HTTPs.\n\n## API Key related error response\n\nIf an API Key is missing, malformed, or invalid, you will receive a ```403 Access Denied``` response code and the following JSON response:\n\n```\n{\n \"errors\": {\n \"auth\": \"Authentication failed.\"\n },\n \"code\": 403\n}\n```\n\n----\n\n## Security\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.\n\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.\n\n----\n\n## Timestamps\n\nAll request timestamps show be formatted as ISO8601, e.g. `YYYY-MM-DDTHH:MM:SS`. The timezone is always UTC.\nTimestamps in most responses are returned in the format `YYYY-MM-DD HH:MM:SS`, in the local timezone of your account. See the details for each request for more information.\n\n----\n\n## Error Codes\n\nAlways check if your API call was successful or resulted in error. You may check the following\n\n* 200 OK response header.\n* 4XX ERROR response header\n* 5XX ERROR response header\n\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 description for details, e.g. which field caused an error or which resource you don’t have access to.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Status CodeErrorDescriptionExample Response
200N/aRequest Successful.{\"code\":200,\"errors\":0,\"message\":\"\"}
400Validation FailedThere was a validation error. Check the supplied response for more details.{\"code\":400,\"message\":\"Validation Failed\",\"errors\":{\"children\":{\"message\":[],\"number\":{\"errors\":[\"Number field contains invalid characters\"]},\"senderid\":[],\"reference\":[]}}}
402Not enough creditsIf your account is out of SMS Credits the system will issue a 402 Payment Required response.{\"code\":402,\"errors\":402,\"message\":\"Not enough credits\"}
403Authentication failedIf your API Keys are invalid or disabled the system will issue a 403 Forbidden response.{\"errors\":{\"auth\":\"Authentication failed.\"},\"code\":403}
405Method Not AllowedIf your application tries to make a GET Request to the API the system will issue a 405 Method Not Allowed response.{\"code\":405,\"errors\":405,\"message\":\"GET Method Not Allowed\"}
406Number is opted outIf you try to message a number that is in your Opt Out list the system will issue a 406 Not Acceptable response.{\"code\":406,\"errors\":406,\"message\":\"Number is opted out\"}
409Country not supported/td>\n If you try to message a number outside of Australia or New Zealand the system will issue a 409 Conflict response.{\"code\":409,\"errors\":409,\"message\":\"Country not supported\"}
\n\n## Troubleshooting common API connection problems.\n\nTo 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.\n\nCheck your network topology, firewalls, proxies and other network components that maybe causing your server to not be able to connect.\n\nIf you are receiving an error status code, first check the request body for detailed error information.\n\n----\n\n## Still got problems?\n\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.\n\n**API endpoint being used?**\n\ni.e. `/v1/messages`\n\n**Language being used?**\n\ni.e. `php`, `C#`, etc\n\n**Are you using the relevant library or package?**\n\nY/N\n\n**Have you tested the failing request in Postman? If not, please reproduce the issue there**\n\nY/N\n\n**What are you trying to achieve with the API request?**\n\ni.e. I'm trying to send a sms message to a client with a custom sender ID,\n\n**What error(s) are you getting from the API? Include the description given in the response.**\n\ni.e. `Number is opted out`\n\n**NB: WE MUST HAVE A HTTP REQUEST/RESPONSE CAPTURE (Without this we cannot help you)**\n\nAcceptable formats for this are:\n\n- Curl Snippet (this can be [exported from postman](https://stackoverflow.com/questions/49432735/converting-a-postman-request-to-curl))\n- HAR (Http Archive)\n- Raw HTTP Request\n\nPlease provide the output of attempting the relevant API call with curl, as provided on the API's documentation page.\n\nIf possible, please provide a copy of the relevant source code making the request.\n\n\n\n----\n\n# API Client Libraries\n\nWe maintain client libraries to make integration easy as pie. Looking for a client library we don't have? Reach out to our support and make a suggestion!\n\n* [Client Library for PHP](https://github.com/touchsms/touchsms-PHP-API)\n* [Client Library for NodeJS](https://github.com/touchsms/touchsms-node)\n\n\n\n# HTTP Callbacks\n\nThe best method of getting immediate notifications on the events like SMS delivery or incoming messages is to set up callback (webhook) URLs. We will notify this URL immediately\nafter the event occurs with a `POST` request and, if the call was unsuccessful, we will retry up to `20` times.\n\nCallback settings:\n[platform.touchsms.com.au/apis/replies](https://platform.touchsms.com.au/apis/replies)\n\nYou can enable or disable both reply and DLR callbacks from this page.\n\n----\n\n## Retries\n\nIf we are not able to reach your callback endpoint, we will retry the request up to `20` times.\n\n## Delivery (DLR) Callback\n\nDelivery Receipts or `DLRs`, are notifications received from the carrier relating to the success and statuses of an attempted SMS Delivery.\n\nThey are delivered as a `POST` request, with the following body params:\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ParameterDescription
referenceYour reference code provided when submitting the message over the RESTful API.
descriptionThe delivery status of your message, this can be one of two options

\n

DELIVERED

\n

FAILED

timeThe time that the receipt was generated, will be in the format of;

\n

YYYY-MM-DD HH:MM:SS

timezoneThe timezone of the of the timestamp provided, the timezone is always set to your account timezone for ease of use.
\n\n----\n\n## Incoming SMS Callback\n\nIncoming SMS are similar to DLRs, except that they contain an incoming message instead of a message status.\n\nThey are delivered as a `POST` request, with the following body params:\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ParameterDescription
referenceYour reference code provided when submitting the message over the RESTful API.
messageThe message that was sent as a reply
numberThe mobile number that sent the reply (International format)
timeThe time that the receipt was generated, will be in the format of;

\n

YYYY-MM-DD HH:MM:SS

timezoneThe timezone of the of the timestamp provided, the timezone is always set to your account timezone for ease.
\n\n# Testing Numbers\n\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.\n\n### Valid Number\n**61491578888**\n\nThis will cause the API to skip saving this message, but return a result as if it was a normally processed message\n\n### Invalid Number\n**61491570156**\n\nThis will cause the API to respond with an error that the number is not valid\n\n### Opt Out\n**61491570157**\n\nThis will cause the API to respond like the number is opted out","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"14542603","team":1575331,"collectionId":"586a2d10-243f-4c77-afa1-ea727c468065","publishedId":"TWDTMeLs","public":true,"publicUrl":"https://documenter-api.postman.tech/view/14542603/TWDTMeLs","privateUrl":"https://go.postman.co/documentation/14542603-586a2d10-243f-4c77-afa1-ea727c468065","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"b4c630"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2021-03-15T00:02:54.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"TouchSMS","id":"b6bdd782-b1da-425e-a0fc-17a9c5b0aff1","owner":"14542603","values":[{"key":"baseUrl","value":"https://platform.touchsms.com.au/rest","enabled":true},{"key":"username","value":"3807-JsreNbbGqeoq482RF0","enabled":true},{"key":"token","value":"k2s9zNmJCIY8ihpmUqnr","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/b7b4d1e56ee4909f0428f99e300d40fdd411a1c1b17e8ca4e9a10b42c231ce2d","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"TouchSMS","value":"14542603-b6bdd782-b1da-425e-a0fc-17a9c5b0aff1"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/TWDTMeLs"}