openapi-directory/api/thesmsworks.co.uk.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"openapi":"3.0.0","info":{"contact":{"x-twitter":"thesmsworks"},"description":"The SMS Works provides a low-cost, reliable SMS API for developers. Pay only for delivered texts, all failed messages are refunded.","title":"The SMS Works API","version":"1.8.0","x-apisguru-categories":["messaging"],"x-logo":{"url":"https://twitter.com/thesmsworks/profile_image?size=original"},"x-origin":[{"format":"swagger","url":"https://api.thesmsworks.co.uk/api/swagger/swagger.yaml","version":"2.0"}],"x-providerName":"thesmsworks.co.uk"},"paths":{"/batch/any":{"post":{"description":"Sends a collection of unique SMS messages. Batches may contain up to 5000 messages at a time.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageArray"}}},"description":"An array of messages","required":true},"responses":{"201":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/BatchMessageResponse"}}}},"402":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["batch messages"]}},"/batch/schedule":{"post":{"description":"Schedules a batch of SMS messages to be sent at the date time you specify","requestBody":{"$ref":"#/components/requestBodies/BatchMessage"},"responses":{"201":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ScheduledBatchResponse"}}}},"402":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["batch messages"]}},"/batch/send":{"post":{"description":"Send a single SMS message to multiple recipients.  Batches may contain up to 5000 messages at a time.","requestBody":{"$ref":"#/components/requestBodies/BatchMessage"},"responses":{"201":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/BatchMessageResponse"}}}},"402":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["batch messages"]}},"/batch/{batchid}":{"get":{"description":"Retrieve all messages in a batch with the given batch ID","parameters":[{"description":"The ID of the batch you would like returned","in":"path","name":"batchid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"items":{"$ref":"#/components/schemas/MessageResponse"},"type":"array"}}}},"404":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["batch messages"]}},"/batches/schedule/{batchid}":{"delete":{"description":"Cancels a scheduled SMS message","parameters":[{"description":"The ID of the batch you would like returned","in":"path","name":"batchid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/CancelledMessageResponse"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["batch messages"]}},"/credits/balance":{"get":{"description":"Returns the number of credits currently available on the account","responses":{"200":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/CreditsResponse"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["credits"]}},"/message/flash":{"post":{"description":"Sends an SMS flash message, which appears on the recipients lock screen","operationId":"sendFlashMessage","requestBody":{"$ref":"#/components/requestBodies/Message"},"responses":{"201":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}}},"402":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["messages"]},"x-swagger-router-controller":"flash"},"/message/schedule":{"post":{"description":"Schedules an SMS message to be sent at the date-time you specify","requestBody":{"$ref":"#/components/requestBodies/Message"},"responses":{"200":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"items":{"$ref":"#/components/schemas/ScheduledMessageResponse"},"type":"array"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["messages"]},"x-swagger-router-controller":"smpp-client"},"/message/send":{"post":{"description":"Send an SMS Message","requestBody":{"$ref":"#/components/requestBodies/Message"},"responses":{"201":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}}},"402":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["messages"]}},"/messages":{"post":{"description":"Retrieve up to 1000 messages matching your search criteria","requestBody":{"$ref":"#/components/requestBodies/Query"},"responses":{"200":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"items":{"$ref":"#/components/schemas/MessageResponse"},"type":"array"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["messages"]}},"/messages/failed":{"post":{"description":"Get failed messages matching your search criteria","requestBody":{"$ref":"#/components/requestBodies/Query"},"responses":{"200":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"items":{"$ref":"#/components/schemas/MessageResponse"},"type":"array"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["messages"]}},"/messages/inbox":{"post":{"description":"Get unread uncoming messages matching your search criteria","requestBody":{"$ref":"#/components/requestBodies/Query"},"responses":{"200":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"items":{"$ref":"#/components/schemas/MessageResponse"},"type":"array"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["messages"]}},"/messages/schedule":{"get":{"description":"Returns a list of messages scheduled from your account, comprising any messages scheduled in the last 3 months and any scheduled to send in the future","responses":{"200":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ScheduledMessagesResponse"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["messages"]}},"/messages/schedule/{messageid}":{"delete":{"description":"Cancels a scheduled SMS message","parameters":[{"description":"The ID of the message you would like returned","in":"path","name":"messageid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/CancelledMessageResponse"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["messages"]}},"/messages/{messageid}":{"delete":{"description":"Delete the message with the mathcing messageid","parameters":[{"description":"The ID of the message you would like returned","in":"path","name":"messageid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/DeletedMessageResponse"}}}},"400":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["messages"]},"get":{"description":"Retrieve a logged message by the message ID","parameters":[{"description":"The ID of the message you would like returned","in":"path","name":"messageid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"404":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["messages"]}},"/swagger":{"x-swagger-pipe":"swagger_raw"},"/utils/errors/{errorcode}":{"get":{"description":"Returns a sample error object for the given error code. Useful for designing code to react to errors when they occur for real.","parameters":[{"description":"The code of the error you would like returned","in":"path","name":"errorcode","required":true,"schema":{"type":"string"}}],"responses":{"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ExtendedErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["utils"]}},"/utils/test":{"get":{"description":"Returns the customer ID to the caller","responses":{"200":{"description":"Success","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/TestResponse"}}}},"default":{"description":"Error","content":{"application/json;charset=UTF-8":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}}}},"security":[{"JWT":[]}],"tags":["utils"]}}},"servers":[{"url":"https://api.thesmsworks.co.uk/v1"}],"components":{"requestBodies":{"Query":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Query"}}},"required":true},"BatchMessage":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchMessage"}}},"description":"Message properties","required":true},"Message":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}},"description":"Message properties","required":true}},"securitySchemes":{"JWT":{"in":"header","name":"Authorization","type":"apiKey"}},"schemas":{"BatchMessage":{"description":"SMS Message Batch","properties":{"content":{"description":"Message to send to the recipient","example":"My super awesome batch message","type":"string"},"deliveryreporturl":{"description":"The url to which we should POST delivery reports to for this message. If none is specified, we'll use the global delivery report URL that you've configured on your account page.","example":"http://your.domain.com/delivery/report/path","type":"string"},"destinations":{"description":"Telephone numbers of each of the recipients","example":["447777777777","447777777778","447777777779"],"items":{"type":"string"},"type":"array"},"schedule":{"description":"Date-time at which to send the batch. This is only used by the batch/schedule service.","example":"Wed Jul 19 2017 20:26:28 GMT+0100 (BST)","type":"string"},"sender":{"description":"The sender of the message. Should be no longer than 11 characters for alphanumeric or 15 characters for numeric sender ID's. No spaces or special characters.","example":"YourCompany","type":"string"},"tag":{"description":"An identifying label for the message, which you can use to filter and report on messages you've sent later. Ideal for campaigns. A maximum of 280 characters.","example":"SummerSpecial","type":"string"},"ttl":{"description":"The number of minutes before the delivery report is deleted. Optional. Omit to prevent delivery report deletion. Integer.","example":10,"type":"number"},"validity":{"description":"The optional number of minutes to attempt delivery before the message is marked as EXPIRED. Optional. The default is 2880 minutes. Integer.","example":1440,"maximum":2880,"minimum":1,"type":"number"}},"required":["sender","destinations","content"]},"BatchMessageResponse":{"properties":{"batchid":{"example":2586749,"type":"string"},"status":{"example":"SCHEDULED","type":"string"}},"required":["batchid","status"]},"CancelledMessageResponse":{"properties":{"messageid":{"example":5620320,"type":"string"},"status":{"example":"CANCELLED","type":"string"}},"required":["messageid","status"]},"CreditsResponse":{"properties":{"credits":{"description":"The number of remaining credits on your SMS Works account. Floating point number.","example":180,"type":"number"}},"required":["credits"]},"DeletedMessageResponse":{"properties":{"messageid":{"example":5620320,"type":"string"},"status":{"example":"DELETED","type":"string"}},"required":["messageid","status"]},"ErrorModel":{"properties":{"message":{"type":"string"}},"required":["message"],"type":"object"},"ExtendedErrorModel":{"allOf":[{"$ref":"#/components/schemas/ErrorModel"},{"properties":{"errorCode":{"description":"Numeric code used to identify the error. Integer.","type":"number"},"permanent":{"type":"boolean"},"status":{"type":"string"}},"required":["errorCode","status"],"type":"object"}]},"Message":{"description":"SMS message object","properties":{"content":{"description":"Message to send to the recipient. Content can be up to 1280 characters in length. Messages of 160 characters or fewer are charged 1 credit. If your message is longer than 160 characters then it will be broken down in to chunks of 153 characters before being sent to the recipient's handset, and you will be charged 1 credit for each 153 characters. Messages sent to numbers registered outside the UK will be typically charged double credits, but for certain countries may be charged fractions of credits (e.g. 2.5). Please contact us for rates for each country.","example":"Your super awesome message","type":"string"},"deliveryreporturl":{"description":"The url to which we should POST delivery reports to for this message. If none is specified, we'll use the global delivery report URL that you've configured on your account page.","example":"http://your.domain.com/delivery/report/path","type":"string"},"destination":{"description":"Telephone number of the recipient","example":"447777777777","type":"string"},"metadata":{"example":[{"key":"myKey1","value":"myValue1"},{"key":"myKey2","value":"myValue2"}],"items":{"type":"object"},"properties":{"schema":{"$ref":"#/components/schemas/MetaData"}},"type":"array"},"responseemail":{"description":"An optional list of email addresses to forward responses to this specific message to. An SMS Works Reply Number is required to use this feature.","example":["my.email@mycompany.co.uk","my.other.email@mycompany.co.uk"],"items":{"type":"string"},"type":"array"},"schedule":{"description":"Date at which to send the message. This is only used by the message/schedule service and can be left empty for other services.","example":"Sun Sep 03 2020 15:34:23 GMT+0100 (BST)","type":"string"},"sender":{"description":"The sender of the message. Should be no longer than 11 characters for alphanumeric or 15 characters for numeric sender ID's. No spaces or special characters.","example":"YourCompany","type":"string"},"tag":{"description":"An identifying label for the message, which you can use to filter and report on messages you've sent later. Ideal for campaigns. A maximum of 280 characters.","example":"SummerSpecial","type":"string"},"ttl":{"description":"The optional number of minutes before the delivery report is deleted. Optional. Omit to prevent delivery report deletion. Integer.","example":10,"type":"number"},"validity":{"description":"The optional number of minutes to attempt delivery before the message is marked as EXPIRED. Optional. The default is 2880 minutes. Integer.","example":1440,"maximum":2880,"minimum":1,"type":"number"}},"required":["sender","destination","content"],"type":"object"},"MessageArray":{"description":"An array of Messages","items":{"$ref":"#/components/schemas/Message"}},"MessageResponse":{"properties":{"batchid":{"example":"2586749","type":"string"},"content":{"example":"My super awesome message","type":"string"},"created":{"example":"Wed Jul 19 2017 20:53:46 GMT+0100 (BST)","type":"string"},"customerid":{"example":"0fca8c3c-6cbc-11e7-8154-a6006ad3dba0","type":"string"},"deliveryreporturl":{"example":"https://your.domain.com/delivery/report/path","type":"string"},"destination":{"example":"447777777777","type":"number"},"failurereason":{"properties":{"code":{"description":"Numeric code that defines the error. Integer.","example":34,"type":"number"},"details":{"example":"Handset error","type":"string"},"permanent":{"example":false,"type":"boolean"}},"type":"object"},"id":{"example":123456789,"type":"string"},"identifier":{"example":7777777777,"type":"string"},"keyword":{"example":"CALRISSIAN","type":"string"},"messageid":{"example":123456789,"type":"string"},"modified":{"example":"Wed Jul 19 2017 20:53:49 GMT+0100 (BST)","type":"string"},"schedule":{"example":"Wed Jul 19 2017 20:53:45 GMT+0100 (BST)","type":"string"},"sender":{"example":"YourCompany","type":"string"},"status":{"example":"DELIVERED","type":"string"},"tag":{"example":"campaign2","type":"string"}},"required":["content","created","customerid","destination","messageid","modified","schedule","status","sender","tag"]},"MetaData":{"description":"Key/value pair that will be returned to you in the API call response.","properties":{"key":{"description":"key of the key/value pair","example":"myKey","type":"string"},"value":{"description":"value of the key/value pair","example":"myValue","type":"string"}}},"Query":{"description":"search parameters for querying the message database","properties":{"credits":{"description":"The number of credits used on the message. Floating point number.","example":2,"type":"number"},"destination":{"description":"The phone number of the recipient. Start UK numbers with 44 and drop the leading 0.","example":"447777777777","type":"string"},"from":{"description":"The date-time from which you would like matching messages","example":"Wed Jul 12 2017 20:26:28 GMT+0100 (BST)","type":"string"},"keyword":{"description":"The keyword used in the inbound message","example":"SKYWALKER","type":"string"},"limit":{"description":"The maximum number of messages that you would like returned in this call. The default is 1000.","example":1000,"type":"number"},"metadata":{"description":"An array of objects containing metadata key/value pairs that have been saved on messages.","example":[{"key":"myKey1","value":"myValue1"},{"key":"myKey2","value":"myValue2"}],"items":{"type":"object"},"properties":{"schema":{"$ref":"#/components/schemas/MetaData"}},"type":"array"},"sender":{"description":"The sender of the message (this can be the configured sender name for an outbound message or the senders phone number for an inbound message).","example":"YourCompany","type":"string"},"skip":{"description":"The number of results you would like to ignore before returning messages. In combination with the 'limit' parameter his can be used to page results, so that you can deal with a limited number in your logic at each time.","example":2000,"type":"number"},"status":{"description":"The status of the messages you would like returned (either 'SENT', 'DELIVERED', 'EXPIRED', 'UNDELIVERABLE', 'REJECTED' or 'INCOMING')","example":"SENT","type":"string"},"to":{"description":"The date-time to which you would like matching messages","example":"Wed Jul 19 2017 20:26:28 GMT+0100 (BST)","type":"string"},"unread":{"description":"In queries for incoming messages ('status' is 'INCOMING'), specify whether you explicitly want unread messages (true) or read messages (false). Omit this parameter in other circumstances.","type":"boolean"}}},"ScheduledBatchResponse":{"properties":{"batchid":{"example":3200562,"type":"string"},"status":{"example":"SCHEDULED","type":"string"}},"required":["batchid","status"]},"ScheduledMessage":{"description":"the scheduled message content","properties":{"content":{"description":"Message to be sent to the recipient","example":"My super awesome scheduled message","type":"string"},"destination":{"description":"For single scheduled messages, the mobile number of the recipient","example":"447777777777","type":"string"},"destinations":{"description":"For batch messages, the mobile numbers of each of the recipients","example":["447777777777","447777777778","447777777779"],"items":{"type":"string"},"type":"array"},"schedule":{"description":"Date-time at which to send the batch. This is only used by the batch/schedule service.","example":"Wed Jul 19 2017 20:26:28 GMT+0100 (BST)","type":"string"},"sender":{"description":"The sender of the message. Should be no longer than 11 characters for alphanumeric or 15 characters for numeric sender ID's. No spaces or special characters.","example":"YourCompany","type":"string"}}},"ScheduledMessageResponse":{"properties":{"messageid":{"example":123456789,"type":"string"},"status":{"example":"SCHEDULED","type":"string"}},"required":["messageid","status"]},"ScheduledMessagesResponse":{"description":"details of a message scheduled to be sent at a specified date and time","properties":{"batch":{"description":"Describes whether the a batch of messages has been scheduled, or just a single message","type":"boolean"},"id":{"description":"The scheduled message ID","example":"1910600","type":"string"},"message":{"example":{"content":"Greetings on schedule!","destination":"07777777777","schedule":"2025-06-15T13:47:09.240Z","sender":"MyCompany"},"properties":{"schema":{"$ref":"#/components/schemas/ScheduledMessage"}},"type":"object"},"status":{"description":"The status of the scheduled message (either 'SCHEDULED', 'PROCESSED' or 'CANCELLED')","example":"PROCESSED","type":"string"}}},"SendMessageResponse":{"properties":{"credits":{"description":"The number of remaining credits on your SMS Works account. Floating point number.","example":180,"type":"number"},"creditsUsed":{"description":"The number of credits used to send the message. Floating point number.","example":2,"type":"number"},"messageid":{"example":123456789,"type":"string"},"status":{"example":"SENT","type":"string"}},"required":["messageid","status","credits","creditsUsed"]},"TestResponse":{"properties":{"message":{"type":"string"}},"required":["message"]}}}}