openapi: 3.0.1 info: title: The SMS Works API description: The SMS Works provides a low-cost, reliable SMS API for developers. Pay only for delivered texts, all failed UK messages are refunded. version: 1.10.0 termsOfService: https://thesmsworks.co.uk/terms x-logo: url: https://qa.thesmsworks.co.uk/docs/logo-transparent.png altText: The SMS Works href: https://thesmsworks.co.uk contact: name: SMS Works Support url: https://thesmsworks.co.uk/contact email: support@thesmsworks.co.uk servers: - url: https://api.thesmsworks.co.uk/v1 paths: /message/send: post: tags: - Messages description: Send an SMS Message requestBody: description: Message properties content: application/json: schema: $ref: '#/components/schemas/Message' required: true 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: [] x-codegen-request-body-name: smsMessage /message/flash: post: tags: - Messages description: Sends an SMS flash message operationId: sendFlashMessage requestBody: description: Message properties content: application/json: schema: $ref: '#/components/schemas/Message' required: true 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: [] x-codegen-request-body-name: smsMessage x-swagger-router-controller: flash /message/schedule: post: tags: - Messages description: Schedules an SMS message to be sent at the date-time you specify requestBody: description: Message properties content: application/json: schema: $ref: '#/components/schemas/Message' required: true responses: 200: description: Success content: application/json;charset=UTF-8: schema: type: array items: $ref: '#/components/schemas/ScheduledMessageResponse' default: description: Error content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExtendedErrorModel' security: - JWT: [] x-codegen-request-body-name: smsMessage x-swagger-router-controller: smpp-client /binary/send: post: tags: - Messages description: Send a binary SMS Message. Message content should be hex encoded (e.g. '65 54 74 73 6d 20 73 65 61 73 65 67 2e') requestBody: description: Message properties content: application/json: schema: $ref: '#/components/schemas/Message' required: true 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: [] x-codegen-request-body-name: smsMessage /messages: post: tags: - Messages description: Retrieve up to 1000 messages matching your search criteria requestBody: content: application/json: schema: $ref: '#/components/schemas/Query' required: true responses: 200: description: Success content: application/json;charset=UTF-8: schema: type: array items: $ref: '#/components/schemas/MessageResponse' default: description: Error content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExtendedErrorModel' security: - JWT: [] x-codegen-request-body-name: query /messages/inbox: post: tags: - Messages description: Get unread uncoming messages matching your search criteria requestBody: content: application/json: schema: $ref: '#/components/schemas/Query' required: true responses: 200: description: Success content: application/json;charset=UTF-8: schema: type: array items: $ref: '#/components/schemas/MessageResponse' default: description: Error content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExtendedErrorModel' security: - JWT: [] x-codegen-request-body-name: query /messages/failed: post: tags: - Messages description: Get failed messages matching your search criteria requestBody: content: application/json: schema: $ref: '#/components/schemas/Query' required: true responses: 200: description: Success content: application/json;charset=UTF-8: schema: type: array items: $ref: '#/components/schemas/MessageResponse' default: description: Error content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExtendedErrorModel' security: - JWT: [] x-codegen-request-body-name: query /messages/schedule: get: tags: - Messages 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: [] /messages/{messageid}: get: tags: - Messages description: Retrieve a logged message by the message ID parameters: - name: messageid in: path description: The ID of the message you would like returned 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: [] delete: tags: - Messages description: Delete the message with the mathcing messageid parameters: - name: messageid in: path description: The ID of the message you would like returned 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: [] /messages/schedule/{messageid}: delete: tags: - Messages description: Cancels a scheduled SMS message parameters: - name: messageid in: path description: The ID of the message you would like returned 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: [] /messages/volume: get: tags: - Messages description: Retrieve the number of messages sent since midnight last night responses: 200: description: Success content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/MessageVolumeResponse' default: description: Error content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExtendedErrorModel' security: - JWT: [] /batch/send: post: tags: - Batch Messages description: Send a single SMS message to multiple recipients. Batches may contain up to 5000 messages at a time. requestBody: description: Message properties content: application/json: schema: $ref: '#/components/schemas/BatchMessage' 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: [] x-codegen-request-body-name: smsMessage /batch/any: post: tags: - Batch Messages description: Sends a collection of unique SMS messages. Batches may contain up to 5000 messages at a time. requestBody: description: An array of messages content: application/json: schema: $ref: '#/components/schemas/MessageArray' 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: [] x-codegen-request-body-name: messages /batch/{batchid}: get: tags: - Batch Messages description: Retrieve all messages in a batch with the given batch ID parameters: - name: batchid in: path description: The ID of the batch you would like returned required: true schema: type: string responses: 200: description: Success content: application/json;charset=UTF-8: schema: type: array items: $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: [] /batch/schedule: post: tags: - Batch Messages description: Schedules a batch of SMS messages to be sent at the date time you specify requestBody: description: Message properties content: application/json: schema: $ref: '#/components/schemas/BatchMessage' required: true 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: [] x-codegen-request-body-name: smsMessage /batches/schedule/{batchid}: delete: tags: - Batch Messages description: Cancels a scheduled SMS message parameters: - name: batchid in: path description: The ID of the batch you would like returned 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: [] /otp/send: post: tags: - One-Time Password description: Generates and sends a One-Time Password requestBody: description: OTP properties content: application/json: schema: $ref: '#/components/schemas/OTP' required: true responses: 201: description: Success content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/OTPResponse' default: description: Error content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ErrorModel' security: - JWT: [] x-codegen-request-body-name: otp /otp/verify: post: tags: - One-Time Password description: Generates and sends a One-Time Password requestBody: description: One-Time Password content: application/json: schema: $ref: '#/components/schemas/OTPVerify' required: true responses: 200: description: Success content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/OTPVerifyResponse' 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: [] x-codegen-request-body-name: passcode /otp/{messageid}: get: tags: - One-Time Password description: Retrieve an OTP by it's message ID parameters: - name: messageid in: path description: The ID of the OTP you would like returned required: true schema: type: string responses: 200: description: Success content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/OTPVerifyResponse' 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: [] /credits/balance: get: tags: - Credits 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: [] /utils/test: get: tags: - Utils 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: [] /utils/errors/{errorcode}: get: tags: - Utils 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: - name: errorcode in: path description: The code of the error you would like returned required: true schema: type: string responses: default: description: Error content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ExtendedErrorModel' security: - JWT: [] /swagger: x-swagger-pipe: swagger_raw components: schemas: TestResponse: required: - message type: object properties: message: type: string CreditsResponse: required: - credits type: object properties: credits: type: number description: The number of remaining credits on your SMS Works account. Floating point number. example: 180.0 Message: required: - content - destination - sender type: object properties: sender: type: string 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 destination: type: string description: Telephone number of the recipient example: "447777777777" content: type: string 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 deliveryreporturl: type: string 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 schedule: type: string 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) tag: type: string 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 ttl: type: number description: The optional number of minutes before the delivery report is deleted. Optional. Omit to prevent delivery report deletion. Integer. example: 10.0 responseemail: type: array 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 metadata: type: object properties: schema: $ref: '#/components/schemas/MetaData' example: - key: myKey1 value: myValue1 - key: myKey2 value: myValue2 validity: maximum: 2.88E+3 minimum: 1 type: number 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.0 ai: type: boolean description: Used to determine whether The SMS Works AI Optimiser should be used in the event that the message is just longer than the 1 or 2 credit boundary. This setting overrides the AI Optimiser configuration on your SMS Works account. description: SMS message object MetaData: type: object properties: key: type: string description: key of the key/value pair example: myKey value: type: string description: value of the key/value pair example: myValue description: Key/value pair that will be returned to you in the API call response. MessageArray: type: object description: An array of Messages BatchMessage: required: - content - destinations - sender type: object properties: sender: type: string 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 destinations: type: array description: Telephone numbers of each of the recipients example: - "447777777777" - "447777777778" - "447777777779" items: type: string content: type: string description: Message to send to the recipient example: My super awesome batch message deliveryreporturl: type: string 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 schedule: type: string 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) tag: type: string 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 ttl: type: number description: The number of minutes before the delivery report is deleted. Optional. Omit to prevent delivery report deletion. Integer. example: 10.0 validity: maximum: 2.88E+3 minimum: 1 type: number 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 ai: type: boolean description: Used to determine whether The SMS Works AI Optimiser should be used in the event that the message is just longer than the 1 or 2 credit boundary. This setting overrides the AI Optimiser configuration on your SMS Works account. description: SMS Message Batch ScheduledMessage: type: object properties: sender: type: string 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 content: type: string description: Message to be sent to the recipient example: My super awesome scheduled message destination: type: string description: For single scheduled messages, the mobile number of the recipient example: "447777777777" destinations: type: array description: For batch messages, the mobile numbers of each of the recipients example: - "447777777777" - "447777777778" - "447777777779" items: type: string schedule: type: string 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) description: the scheduled message content ScheduledMessagesResponse: type: object properties: status: type: string description: The status of the scheduled message (either 'SCHEDULED', 'PROCESSED' or 'CANCELLED') example: PROCESSED id: type: string description: The scheduled message ID example: "1910600" batch: type: boolean description: Describes whether the a batch of messages has been scheduled, or just a single message message: type: object properties: schema: $ref: '#/components/schemas/ScheduledMessage' example: sender: MyCompany destination: "07777777777" content: Greetings on schedule! schedule: 2021-10-28T14:10:00+01:00 description: details of a message scheduled to be sent at a specified date and time MessageVolumeResponse: type: object properties: volume: type: number description: the number of messages sent from your account since midnight last night Query: type: object properties: status: type: string description: The status of the messages you would like returned (either 'SENT', 'DELIVERED', 'EXPIRED', 'UNDELIVERABLE', 'REJECTED' or 'INCOMING') example: SENT credits: type: number description: The number of credits used on the message. Floating point number. example: 2.0 destination: type: string description: The phone number of the recipient. Start UK numbers with 44 and drop the leading 0. example: "447777777777" sender: type: string 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 keyword: type: string description: The keyword used in the inbound message example: SKYWALKER from: type: string description: The date-time from which you would like matching messages example: Wed Jul 12 2017 20:26:28 GMT+0100 (BST) to: type: string description: The date-time to which you would like matching messages example: Wed Jul 19 2017 20:26:28 GMT+0100 (BST) limit: type: number description: The maximum number of messages that you would like returned in this call. The default is 1000. example: 1000.0 skip: type: number 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.0 unread: type: boolean 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. metadata: type: object properties: schema: $ref: '#/components/schemas/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 description: search parameters for querying the message database SendMessageResponse: required: - credits - creditsUsed - messageid - status type: object properties: messageid: type: string example: "123456789" status: type: string example: SENT credits: type: number description: The number of remaining credits on your SMS Works account. Floating point number. example: 180.0 creditsUsed: type: number description: The number of credits used to send the message. Floating point number. example: 2.0 ScheduledMessageResponse: required: - messageid - status type: object properties: messageid: type: string example: "123456789" status: type: string example: SCHEDULED ScheduledBatchResponse: required: - batchid - status type: object properties: batchid: type: string example: "3200562" status: type: string example: SCHEDULED CancelledMessageResponse: required: - messageid - status type: object properties: messageid: type: string example: "5620320" status: type: string example: CANCELLED DeletedMessageResponse: required: - messageid - status type: object properties: messageid: type: string example: "5620320" status: type: string example: DELETED BatchMessageResponse: required: - batchid - status type: object properties: batchid: type: string example: "2586749" status: type: string example: SCHEDULED MessageResponse: required: - content - created - customerid - destination - messageid - modified - schedule - sender - status - tag type: object properties: batchid: type: string example: "2586749" content: type: string example: My super awesome message created: type: string example: Wed Jul 19 2017 20:53:46 GMT+0100 (BST) customerid: type: string example: 0fca8c3c-6cbc-11e7-8154-a6006ad3dba0 deliveryreporturl: type: string example: https://your.domain.com/delivery/report/path destination: type: number example: 447777777777 failurereason: type: object properties: code: type: number description: Numeric code that defines the error. Integer. example: 34.0 details: type: string example: Handset error permanent: type: boolean example: false id: type: string example: "123456789" identifier: type: string example: "7777777777" keyword: type: string example: CALRISSIAN messageid: type: string example: "123456789" modified: type: string example: Wed Jul 19 2017 20:53:49 GMT+0100 (BST) schedule: type: string example: Wed Jul 19 2017 20:53:45 GMT+0100 (BST) status: type: string example: DELIVERED sender: type: string example: YourCompany tag: type: string example: campaign2 OTP: type: object properties: sender: type: string 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 destination: type: string description: The phone number of the recipient. example: "7777777777" length: type: object description: The length of the generated passcode. The default length is 6 characters, which will apply if this parameter is omitted. All generated passcodes are numeric. Optional. template: type: string description: A template to use as the content for the message. You must include the '{{passcode}}' placeholder, which will be replaced by the generated passcode when the message is sent. Optional. example: This is your one-time passcode - {{passcode}} validity: type: number description: The length of time in seconds for which the generated passcode should be valid. Optional. example: 300.0 passcode: type: string description: A passcode you supply for use in the message template. This will be stored on the OTP record in our system for later verification. Optional. example: "123456" metadata: type: object properties: {} description: A JSON object of no longer than 1024 bytes, containing as many parameters as you wish, to store data for use in your application. This will be returned when you verify the passcode. example: customer_id: ABC123 cart_id: XYZ789 description: Parameters for the generation and sending of One-Time Passwords OTPResponse: type: object properties: messageid: type: string description: The messageid of the SMS used to send the OTP. Save this in your application to use when verifying passcodes. example: 52692416-ce9e-45ad-aa1e-14fcee8fa662 status: type: string description: The initial status of the OTP message. example: SENT credits: type: number description: The credit balance on your account example: 561.0 creditsUsed: type: number description: The number of credits used to send this message example: 1.0 messageparts: type: number description: The number of message parts used to send this message example: 1.0 description: Response schema for the /otp/send method OTPVerify: type: object properties: passcode: type: string description: One-Time Passcode submitted to your application example: "123456" description: Schema for the /oyp/verify method OTPVerifyResponse: type: object properties: destination: type: string description: The mobile number that the OTP was sent to example: "447777000000" status: type: string description: The status of the OTP. If the passcode is used within the validity period then this will be 'VERIFIED', otherwise it will be 'EXPIRED' example: VERIFIED passcode: type: number description: The passcode used. example: 123456.0 validity: type: number description: The length of time in seconds for which the generated passcode is valid. example: 300.0 metadata: type: object properties: {} description: A JSON object storing data supplied when this passcode was generated, for use in your application. example: customer_id: ABC123 cart_id: XYZ789 created: type: string description: The ISO 8601 date/time at which this OTP was created example: Tue Apr 25 2023 16:47:00 GMT+0100 (British Summer Time) expires: type: string description: The ISO 8601 date/time at which this OTP expires example: Tue Apr 25 2023 16:57:00 GMT+0100 (British Summer Time) modified: type: string description: The ISO 8601 date/time at which this OTP was modified (typically when it was verified) example: Tue Apr 25 2023 16:49:20 GMT+0100 (British Summer Time) description: Response schema for the /otp/verify method ErrorModel: required: - message type: object properties: message: type: string ExtendedErrorModel: allOf: - $ref: '#/components/schemas/ErrorModel' - required: - errorCode - status type: object properties: errorCode: type: number description: Numeric code used to identify the error. Integer. status: type: string permanent: type: boolean securitySchemes: JWT: type: apiKey name: Authorization in: header