swagger: "2.0"
schemes:
  - https
host: www.winsms.co.za
basePath: /api/rest/v1
info:
  contact:
    email: support@winsms.co.za
    name: WinSMS Support
    url: http://support.winsms.co.za/
    x-twitter: winsms1
  description: WinSMS RESTful API
  termsOfService: https://www.winsms.co.za/terms-conditions/
  title: WINSMS
  version: 1.0.0
  x-apisguru-categories:
    - messaging
  x-logo:
    url: https://twitter.com/winsms1/profile_image?size=original
  x-origin:
    - format: swagger
      url: https://www.winsms.co.za/api/restdocs/swagger.json
      version: "2.0"
  x-providerName: winsms.co.za
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  APIKeyHeader:
    description: Valid API Key supplied by WinSMS
    in: header
    name: AUTHORIZATION
    type: apiKey
security:
  - APIKeyHeader: []
paths:
  /credits/balance:
    get:
      description: |
        Get the current remaining credit balance for the account.

        ***Note*** - The credit balance is expressed as a value with a single decimal place.
      operationId: getCreditBalance
      produces:
        - application/json
      responses:
        "200":
          description: OK
          examples:
            application/json:
              creditBalance: 3645
              statusCode: 200
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            properties:
              creditBalance:
                description: The current remaining credit balance for the account. Contains a single decimal place
                format: double
                type: number
              statusCode:
                description: The http status code returned - reflected in the body for convenience
                type: integer
              timeStamp:
                description: The date/time the request was processed, in the format YYYYMMDDhhmmssSSS
                type: string
              version:
                description: The current version of the API of the endpoint that was called
                type: string
            title: creditBalanceResponse
            type: object
        "401":
          description: Unauthorized
          examples:
            application/json:
              errorMessage: The 'AUTHORIZATION' header was not found. Set the 'AUTHORIZATION' request header to your WinSMS API Key
              statusCode: 401
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "404":
          description: Not found
          examples:
            application/json:
              errorMessage: The resource requested does not exist. Please verify the path, spelling, and capitalisation
              statusCode: 404
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "405":
          description: Method Not Allowed
          examples:
            application/json:
              errorMessage: Request method should be set to 'GET', not 'PUT'.
              statusCode: 405
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "500":
          description: Internal Server Error
          examples:
            application/json:
              errorMessage: An unknown error has occurred - authorising API Key
              statusCode: 500
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
      summary: Get your current WinSMS credit balance
      tags:
        - credits
  /credits/transfer:
    post:
      description: |
        Transfer credits between accounts.
        - From Main account to Sub account.

        - From Sub account to Main account.

        - From Sub account to another Sub account.

        Your WinSMS account number and sub account number/s can be obtained by logging in to the WinSMS Client Zone (www.winsms.co.za/cz) with the main account's credentials.

        The main account number is on the home tab and the sub account numbers are under the sub accounts tab.

        Account numbers should be submitted as integers. Do not add the 'W' prefix.
      operationId: transferCredits
      parameters:
        - description: The details of the credit transfer. Sender account number, recipient account number, and number of credits to transfer.
          in: body
          name: creditTransferDetails
          required: true
          schema:
            example:
              receivingAccountNumber: 10345
              sendingAccountNumber: 7564
              transferQuantity: 100
            properties:
              receivingAccountNumber:
                description: The WinSMS account number of the account to which credits will be added.
                example: 10345
                type: integer
              sendingAccountNumber:
                description: The WinSMS account number of the account from which credits will be deducted.
                example: 7564
                type: integer
              transferQuantity:
                description: The number of credits to transfer from the sending account to the receiving account.
                example: 100
                type: integer
            required:
              - sendingAccountNumber
              - receivingAccountNumber
              - transferQuantity
            title: creditTransferDetails
            type: object
      produces:
        - application/json
      responses:
        "200":
          description: OK
          schema:
            example:
              statusCode: 200
              timeStamp: "20170120152253515"
              transferSuccessful: true
              version: "1.0"
            properties:
              statusCode:
                description: The http status code returned - reflected in the body for convenience
                type: integer
              timeStamp:
                description: The date/time the request was processed, in the format YYYYMMDDhhmmssSSS
                type: string
              transferSuccessful:
                description: A boolean value indictating whether the credits were successfully transfered from the sending account into the receiving account.
                type: boolean
              version:
                description: The current version of the API of the endpoint that was called
                type: string
            title: creditTransferResponse
            type: object
        "400":
          description: Bad Request
          examples:
            application/json:
              errorMessage: Invalid JSON payload received
              statusCode: 400
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "401":
          description: Unauthorized
          examples:
            application/json:
              errorMessage: The 'AUTHORIZATION' header was not found. Set the 'AUTHORIZATION' request header to your WinSMS API Key
              statusCode: 401
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "404":
          description: Not found
          examples:
            application/json:
              errorMessage: The resource requested does not exist. Please verify the path, spelling, and capitalisation
              statusCode: 404
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "405":
          description: Method Not Allowed
          examples:
            application/json:
              errorMessage: Request method should be set to 'POST', not 'GET'.
              statusCode: 405
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "413":
          description: Payload Too Large
          examples:
            application/json:
              errorMessage: "Request POST data is: 205kb. The maximum POST size allowed is 200kb."
              statusCode: 413
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "415":
          description: Unsupported Media Type
          examples:
            application/json:
              errorMessage: Request content-type should be set to 'application/json', not 'text/plain'.
              statusCode: 415
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "422":
          description: Unprocessable Entity
          examples:
            application/json:
              errorMessage: There is an error in the 'recipients' array.
              statusCode: 422
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "500":
          description: Internal Server Error
          examples:
            application/json:
              errorMessage: An unknown error has occurred - authorising API Key
              statusCode: 500
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
      summary: Transfer credits between main and sub accounts.
      tags:
        - credits
  /shortcode/incoming:
    get:
      description: |
        ***Only available to users with a [WinSMS Short/Long Code](https://support.winsms.co.za/winsms-long-short-code-system/).***
        Get a list of all incoming short/long code messages received by the account.

        Only the first 100 incoming short/long code messages will be returned if no ***offset*** and ***limit*** parameters are specified.
      operationId: getShortCodeMessages
      parameters:
        - default: 0
          description: |
            ***Optional*** - The number of items to skip before starting to return results. Default 0. Minimum 0.
          in: query
          minimum: 0
          name: offset
          required: false
          type: integer
        - default: 100
          description: |
            ***Optional*** - The number of items to return. Default 100. Minimum 1. Maximum 1000.
          in: query
          maximum: 1000
          minimum: 1
          name: limit
          required: false
          type: integer
      produces:
        - application/json
      responses:
        "200":
          description: OK
          schema:
            example:
              resultsLimit: 100
              resultsOffset: 3400
              resultsTotalAvailable: 3402
              shortcodeMessages:
                - incomingApiMessageId: 58324
                  messageText: Win Big
                  mobileNumber: "27444444444"
                  receiveTime: "201707252208"
                - incomingApiMessageId: 58336
                  messageText: Savings for me
                  mobileNumber: "27555555555"
                  receiveTime: "201707270952"
              statusCode: 200
              timeStamp: "20170117054658978"
              version: "1.0"
            properties:
              resultsLimit:
                description: |
                  The number of items returned in the results. This is the value specified in the ***limit*** parameter sent to the endpoint. If the parameter was not specified, this defaults to 100.
                type: integer
              resultsOffset:
                description: |
                  The number of items skipped before the results were returned. This is the value specified in the ***offset*** parameter sent to the endpoint. If the parameter was not specified, this defaults to 0.
                type: integer
              resultsTotalAvailable:
                description: |
                  The total number of results available for retrieval. The ***offset*** and ***limit*** properties specify which of the total available results have been returned.
                type: integer
              shortcodeMessages:
                description: |
                  An array of ***shortcodeMessage*** objects containing properties of each incoming shortcode message received by WinSMS.
                items:
                  example:
                    incomingApiMessageId: 58324
                    messageText: Win Big
                    mobileNumber: "27444444444"
                    receiveTime: "201707252208"
                  properties:
                    incomingApiMessageId:
                      description: The unique API message id assigned to this incoming message.
                      example: 58324
                      type: number
                    messageText:
                      description: The text of the incoming SMS message.
                      example: Hello, I'm responding to your advert.
                      type: string
                    mobileNumber:
                      description: The mobile number that sent the SMS message, displayed using the international E164 (without the plus) format
                      example: "27444444444"
                      type: string
                    receiveTime:
                      description: The date and time the message was received by WinSMS, in the format YYYYMMDDHHmm.
                      example: "201707270952"
                      type: string
                  title: shortcodeMessage
                  type: object
                maxItems: 1000
                minItems: 1
                type: array
              statusCode:
                description: The http status code returned - reflected in the body for convenience
                type: integer
              timeStamp:
                description: The date/time the request was processed, in the format YYYYMMDDhhmmssSSS
                type: string
              version:
                description: The current version of the API of the endpoint that was called
                type: string
            title: shortcodeMessageResponse
            type: object
        "401":
          description: Unauthorized
          examples:
            application/json:
              errorMessage: The 'AUTHORIZATION' header was not found. Set the 'AUTHORIZATION' request header to your WinSMS API Key
              statusCode: 401
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "404":
          description: Not found
          examples:
            application/json:
              errorMessage: The resource requested does not exist. Please verify the path, spelling, and capitalisation
              statusCode: 404
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "405":
          description: Method Not Allowed
          examples:
            application/json:
              errorMessage: Request method should be set to 'GET', not 'PUT'.
              statusCode: 405
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "422":
          description: Unprocessable Entity
          examples:
            application/json:
              errorMessage: The offset parameter must be a number greater than or equal to 0.
              statusCode: 422
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "500":
          description: Internal Server Error
          examples:
            application/json:
              errorMessage: An unknown error has occurred - authorising API Key
              statusCode: 500
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
      summary: |
        Get a list of incoming short/long code messages
      tags:
        - shortcode
  /sms/incoming:
    get:
      description: |
        Get a list of all incoming SMS messages received by the account.

        Only the first 100 incoming messages will be returned if no ***offset*** and ***limit*** parameters are specified.
      operationId: getIncomingMessages
      parameters:
        - default: 0
          description: |
            ***Optional*** - The number of items to skip before starting to return results. Default 0. Minimum 0.
          in: query
          minimum: 0
          name: offset
          required: false
          type: integer
        - default: 100
          description: |
            ***Optional*** - The number of items to return. Default 100. Minimum 1. Maximum 1000.
          in: query
          maximum: 1000
          minimum: 1
          name: limit
          required: false
          type: integer
      produces:
        - application/json
      responses:
        "200":
          description: OK
          schema:
            example:
              incomingMessages:
                - incomingApiMessageId: 58324
                  messageText: Thank you for the holiday wishes. Stay safe
                  mobileNumber: "27444444444"
                  outgoingApiMessageId: 2316
                  receiveTime: "201707252208"
                - incomingApiMessageId: 58336
                  messageText: That is much appreciated. Happy holidays to you too
                  mobileNumber: "27555555555"
                  outgoingApiMessageId: 2316
                  receiveTime: "201707270952"
              resultsLimit: 100
              resultsOffset: 3400
              resultsTotalAvailable: 3402
              statusCode: 200
              timeStamp: "20170117054658978"
              version: "1.0"
            properties:
              incomingMessages:
                description: |
                  An array of ***incomingMessage*** objects containing properties of each incoming message.
                items:
                  example:
                    incomingApiMessageId: 58324
                    messageText: Thank you for the holiday wishes. Stay safe
                    mobileNumber: "27444444444"
                    outgoingApiMessageId: 2316
                    receiveTime: "201707252208"
                  properties:
                    incomingApiMessageId:
                      description: |
                        The unique API message id assigned to this incoming message.
                      example: 58324
                      type: number
                    messageText:
                      description: |
                        The text of the incoming SMS message.
                      example: Hello, I'm responding to your SMS invitation
                      type: string
                    mobileNumber:
                      description: |
                        The mobile number that sent the SMS message, displayed using the international E164 (without the plus) format
                      example: "27444444444"
                      type: string
                    outgoingApiMessageId:
                      description: |
                        The API message id of the most recent message sent to the mobile number that responded.
                      example: 2316
                      type: number
                    receiveTime:
                      description: |
                        The date and time the message was received by WinSMS, in the format YYYYMMDDHHmm.
                      example: "201707270952"
                      type: string
                  title: incomingMessage
                  type: object
                maxItems: 1000
                minItems: 1
                type: array
              resultsLimit:
                description: |
                  The number of items returned in the results. This is the value specified in the ***limit*** parameter sent to the endpoint. If the parameter was not specified, this defaults to 100.
                type: integer
              resultsOffset:
                description: |
                  The number of items skipped before the results were returned. This is the value specified in the ***offset*** parameter sent to the endpoint. If the parameter was not specified, this defaults to 0.
                type: integer
              resultsTotalAvailable:
                description: |
                  The total number of results available for retrieval. The ***offset*** and ***limit*** properties specify which of the total available results have been returned.
                type: integer
              statusCode:
                description: The http status code returned - reflected in the body for convenience
                type: integer
              timeStamp:
                description: The date/time the request was processed, in the format YYYYMMDDhhmmssSSS
                type: string
              version:
                description: The current version of the API of the endpoint that was called
                type: string
            title: incomingMessageResponse
            type: object
        "401":
          description: Unauthorized
          examples:
            application/json:
              errorMessage: The 'AUTHORIZATION' header was not found. Set the 'AUTHORIZATION' request header to your WinSMS API Key
              statusCode: 401
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "404":
          description: Not found
          examples:
            application/json:
              errorMessage: The resource requested does not exist. Please verify the path, spelling, and capitalisation
              statusCode: 404
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "405":
          description: Method Not Allowed
          examples:
            application/json:
              errorMessage: Request method should be set to 'GET', not 'PUT'.
              statusCode: 405
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "422":
          description: Unprocessable Entity
          examples:
            application/json:
              errorMessage: The offset parameter must be a number greater than or equal to 0.
              statusCode: 422
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "500":
          description: Internal Server Error
          examples:
            application/json:
              errorMessage: An unknown error has occurred - authorising API Key
              statusCode: 500
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
      summary: Get a list of incoming SMS messages
      tags:
        - sms
  /sms/incoming/optout:
    get:
      description: Get a list of all opt-out SMS messages received by the account, as well as all manually added opt-out numbers.<br>
      operationId: getOptoutMessages
      produces:
        - application/json
      responses:
        "200":
          description: OK
          schema:
            example:
              incomingOptoutMessages:
                - incomingApiMessageId: 58324
                  messageText: STOP
                  mobileNumber: "27444444444"
                  receiveTime: "201707252208"
                - incomingApiMessageId: null
                  messageText: "* MANUALLY ADDED BY USER *"
                  mobileNumber: "27555555555"
                  receiveTime: "201707270952"
              statusCode: 200
              timeStamp: "20170117054658978"
              version: "1.0"
            properties:
              incomingOptoutMessages:
                description: |
                  An array of ***incomingOptoutMessage*** objects containing properties of each opt-out message received.
                items:
                  example:
                    incomingApiMessageId: 58324
                    messageText: STOP
                    mobileNumber: "27444444444"
                    receiveTime: "201707252208"
                  properties:
                    incomingApiMessageId:
                      description: |
                        The unique API message id assigned to this incoming opt-out message.
                      example: 58324
                      type: number
                    messageText:
                      description: |
                        The text of the opt-out SMS message.
                      example: STOP
                      type: string
                    mobileNumber:
                      description: |
                        The mobile number that sent the opt-out SMS message, displayed using the international E164 (without the plus) format
                      example: "27444444444"
                      type: string
                    receiveTime:
                      description: |
                        The date and time the message was received by WinSMS, in the format YYYYMMDDHHmm.
                      example: "201707270952"
                      type: string
                  title: incomingOptoutMessage
                  type: object
                type: array
              statusCode:
                description: The http status code returned - reflected in the body for convenience
                type: integer
              timeStamp:
                description: The date/time the request was processed, in the format YYYYMMDDhhmmssSSS
                type: string
              version:
                description: The current version of the API of the endpoint that was called
                type: string
            title: optoutMessageResponse
            type: object
        "401":
          description: Unauthorized
          examples:
            application/json:
              errorMessage: The 'AUTHORIZATION' header was not found. Set the 'AUTHORIZATION' request header to your WinSMS API Key
              statusCode: 401
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "404":
          description: Not found
          examples:
            application/json:
              errorMessage: The resource requested does not exist. Please verify the path, spelling, and capitalisation
              statusCode: 404
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "405":
          description: Method Not Allowed
          examples:
            application/json:
              errorMessage: Request method should be set to 'GET', not 'PUT'.
              statusCode: 405
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "500":
          description: Internal Server Error
          examples:
            application/json:
              errorMessage: An unknown error has occurred - authorising API Key
              statusCode: 500
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
      summary: Get a list of incoming opt-out SMS messages
      tags:
        - sms
  /sms/outgoing/send:
    post:
      description: |
        Submit 1 or more SMS messages to be sent by WinSMS. Maximum 1000 recipients per request.

        The SMS message text can be a maximum of 918 characters long. If you are submitting a message longer than 160 characters, you should change the value of ***maxSegments***.
      operationId: smsSend
      parameters:
        - description: |
            The message, recipients and delivery options of an SMS message to be sent.
          in: body
          name: newMessageDetails
          required: true
          schema:
            example:
              maxSegments: 3
              message: Happy holidays from all at TelAmeriCorp.
              recipients:
                - clientMessageId: clientId-3023
                  mobileNumber: "27444444444"
                - mobileNumber: "27555555555"
                - clientMessageId: clientId-3024
                  mobileNumber: "276666666666"
              scheduledTime: "201712251430"
            properties:
              maxSegments:
                default: 1
                description: |
                  ***Optional*** - The maximum [GSM Encoded segment count]("https://support.winsms.co.za/rest/GSM") that the message is allowed to utilise.

                  This defaults to 1, allowing for a maximum GSM Encoded message length of 160 characters.

                  The maximum value is 6, which allows for a GSM Encoded message length of 918 characters.

                  If you intend to send a message longer than 160 characters, this value should be specified.
                example: 3
                maximum: 6
                minimum: 1
                type: integer
              message:
                description: The SMS text to be sent.
                example: Happy holidays from all at TelAmeriCorp.
                type: string
              recipients:
                description: An array of messageRecipientDetails objects.
                items:
                  example:
                    clientMessageId: clientId-3023
                    mobileNumber: "27444444444"
                  properties:
                    clientMessageId:
                      description: |
                        ***Optional*** - A parameter to identify an individual SMS message recipient on your system. The clientMessageId parameter is NOT saved by the WinSMS API. 

                        The value of the clientMessageId parameter is returned in the ***submittedRecipientResult*** object of the response, allowing you to match a sent message to a returned message result status.
                      example: clientId-3023
                      type: string
                    mobileNumber:
                      description: A recipient mobile number, using the international E164 (without the plus) format.
                      example: "27444444444"
                      type: string
                  required:
                    - mobileNumber
                  title: messageRecipientDetails
                  type: object
                maxItems: 1000
                minItems: 1
                type: array
              scheduledTime:
                description: |
                  ***Optional*** - The date and time that an SMS should be delivered. If not specified, or is set for a date/time prior to the current date/time, the SMS message will be sent immediately.

                  If specified, this value should have the format YYYYMMDDHHmm.
                example: "201712251430"
                type: string
            required:
              - message
              - recipients
            title: newMessageDetails
            type: object
      produces:
        - application/json
      responses:
        "200":
          description: OK
          schema:
            example:
              recipients:
                - acceptError: ""
                  accepted: true
                  apiMessageId: 2316
                  clientMessageId: clientId-3023
                  creditCost: 1
                  mobileNumber: "27444444444"
                  newCreditBalance: 188.6
                  scheduledTime: "201712251430"
                - acceptError: ""
                  accepted: true
                  apiMessageId: 2317
                  clientMessageId: null
                  creditCost: 1
                  mobileNumber: "27555555555"
                  newCreditBalance: 187.6
                  scheduledTime: "201712251430"
                - acceptError: BADDEST
                  accepted: false
                  apiMessageId: null
                  clientMessageId: clientId-3024
                  creditCost: 0
                  mobileNumber: "276666666666"
                  newCreditBalance: 187.6
                  scheduledTime: null
              statusCode: 200
              timeStamp: "20170117054658978"
              version: "1.0"
            properties:
              recipients:
                description: An array of messageRecipientResponse objects
                items:
                  example:
                    acceptError: ""
                    accepted: true
                    apiMessageId: 2316
                    clientMessageId: clientId-3023
                    creditCost: 1
                    mobileNumber: "27444444444"
                    newCreditBalance: 188.6
                    scheduledTime: "201712251430"
                  properties:
                    acceptError:
                      description: |-
                        If the ***accepted*** value is **false**, this will contain the reason that delivery to the recipient was declined by the API. If the recipient was accepted, this value will be blank. Possible values-
                        | Value | Description |
                        |-------|-------------|
                        |INSUFFICIENT CREDITS | The User Account has insufficient credits to send the message |
                        |ACCOUNTLOCKED | The specified User Account is locked |
                        |TRIALNOT2SELF | Trial Account Restriction – Message not to own number. <a href="https://support.winsms.co.za/trial-account-restrictions/" target="_blank">More Info</a> |
                        |TOOLONG | The <a href="https://en.wikipedia.org/wiki/GSM_03.38#GSM_7-bit_default_alphabet_and_extension_table_of_3GPP_TS_23.038_/_GSM_03.38" target="_blank">GSM 7-bit encoded</a> message length exceeded 918 characters |
                        |BADDEST | An invalid mobile number was supplied, or the recipient has been blacklisted from receiving messages |
                        |OPTEDOUT | The recipient has opted out from receiving any further messages from the user |
                        |WASPADNC | The number is on the WASPA Do Not Contact List (DNC).<br>If you are sending transactional messages then you can bypass the DNC list. <a href="https://zasupport.winsms.co.za/portal/en/kb/articles/marketing-vs-transactional-sms/" target="_blank">Read this article</a> for instructions. |
                        | &nbsp; | &nbsp; |
                        <p>&nbsp;</p>
                      example: BADDEST
                      type: string
                    accepted:
                      description: |
                        A boolean value indicating whether the API accepted the recipient for SMS delivery. This will be **false** If you have insufficient credits or the recipient mobile number supplied is not valid.
                      example: true
                      type: boolean
                    apiMessageId:
                      description: |
                        The WinSMS Message Id assigned to the specific message recipient. This Id can be used to obtain the status of the message, and to delete the message if it was scheduled. If the API did not accept the recipient for delivery, the value will be **null**.
                      example: 2316
                      type: integer
                    clientMessageId:
                      description: |
                        If the optional ***clientMessageId*** value was specified in the recipient object for the recipient, it will be returned here. If not, ***clientMessageId*** will be **null**.
                      example: clientId-3023
                      type: string
                    creditCost:
                      description: |
                        The number of credits deducted from your account for the SMS to this recipient.

                        The credit cost is based on the destination country of the recipient and the length (number of segments) of the message.

                        This credit cost will be reimbursed if the message is scheduled and subsequently deleted.

                        If the recipient is not accepted for delivery, the ***creditCost*** value will be **null**.
                      example: 1.3
                      format: double
                      type: number
                    mobileNumber:
                      description: |
                        The mobile number specified as the ***mobileNumber*** value of the recipient object of the request.
                      example: "27824444444"
                      type: string
                    newCreditBalance:
                      description: |
                        The number of WinSMS credits remaining in your account after processing this recipient.
                      example: 188.6
                      format: double
                      type: number
                    scheduledTime:
                      description: |
                        The date and time that the message was scheduled for delivery to the recipient.

                        If no ***scheduledTime*** value was specified in the request, or the recipient was not accepted for delivery, this value will be **null**.
                      example: "201712251430"
                      type: string
                  title: messageRecipientResponse
                  type: object
                maxItems: 1000
                minItems: 1
                type: array
              statusCode:
                description: The http status code returned - reflected in the body for convenience
                type: integer
              timeStamp:
                description: The date/time the request was processed, in the format YYYYMMDDhhmmssSSS
                type: string
              version:
                description: The current version of the API of the endpoint that was called
                type: string
            title: newMessageResponse
            type: object
        "400":
          description: Bad Request
          examples:
            application/json:
              errorMessage: Invalid JSON payload received
              statusCode: 400
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "401":
          description: Unauthorized
          examples:
            application/json:
              errorMessage: The 'AUTHORIZATION' header was not found. Set the 'AUTHORIZATION' request header to your WinSMS API Key
              statusCode: 401
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "404":
          description: Not found
          examples:
            application/json:
              errorMessage: The resource requested does not exist. Please verify the path, spelling, and capitalisation
              statusCode: 404
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "405":
          description: Method Not Allowed
          examples:
            application/json:
              errorMessage: Request method should be set to 'POST', not 'GET'.
              statusCode: 405
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "413":
          description: Payload Too Large
          examples:
            application/json:
              errorMessage: "Request POST data is: 205kb. The maximum POST size allowed is 200kb."
              statusCode: 413
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "415":
          description: Unsupported Media Type
          examples:
            application/json:
              errorMessage: Request content-type should be set to 'application/json', not 'text/plain'.
              statusCode: 415
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "422":
          description: Unprocessable Entity
          examples:
            application/json:
              errorMessage: There is an error in the 'recipients' array.
              statusCode: 422
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "500":
          description: Internal Server Error
          examples:
            application/json:
              errorMessage: An unknown error has occurred - authorising API Key
              statusCode: 500
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
      summary: Send SMS messages
      tags:
        - sms
  /sms/outgoing/sendmulti:
    post:
      description: |
        Submit multiple different SMS messages to be sent to multiple recipients. Maximum 1000 recipients across all messages.

        Each SMS message text can be a maximum of 918 characters long. If you are submitting a message longer than 160 characters, you should change the value of ***maxSegments***.
      operationId: smsSendBatch
      parameters:
        - description: |
            The messages, recipients and delivery options of multiple SMS messages to be sent.
          in: body
          name: multiMessageDetails
          required: true
          schema:
            example:
              messages:
                - maxSegments: 3
                  message: Happy holidays from all at TelAmeriCorp.
                  recipients:
                    - clientMessageId: clientId-3023
                      mobileNumber: "27444444444"
                    - mobileNumber: "27555555555"
                    - clientMessageId: clientId-3024
                      mobileNumber: "276666666666"
                  scheduledTime: "201712251430"
                - maxSegments: 1
                  message: TelAmeriCorp flash sale - call now for details
                  recipients:
                    - clientMessageId: clientId-0015
                      mobileNumber: "27333333333"
                    - mobileNumber: "27222222222"
                  scheduledTime: "201801010900"
            properties:
              messages:
                items:
                  properties:
                    maxSegments:
                      default: 1
                      description: |
                        ***Optional*** - The maximum [GSM Encoded segment count]("https://support.winsms.co.za/rest/GSM") that the message is allowed to utilise.

                        This defaults to 1, allowing for a maximum GSM Encoded message length of 160 characters.

                        The maximum value is 6, which allows for a GSM Encoded message length of 918 characters.

                        If you intend to send a message longer than 160 characters, this value should be specified.
                      example: 3
                      maximum: 6
                      minimum: 1
                      type: integer
                    message:
                      description: The SMS text to be sent.
                      example: Happy holidays from all at TelAmeriCorp.
                      type: string
                    recipients:
                      description: An array of messageRecipientDetails objects.
                      items:
                        example:
                          clientMessageId: clientId-3023
                          mobileNumber: "27444444444"
                        properties:
                          clientMessageId:
                            description: |
                              ***Optional*** - A parameter to identify an individual SMS message recipient on your system. The clientMessageId parameter is NOT saved by the WinSMS API. 

                              The value of the clientMessageId parameter is returned in the ***submittedRecipientResult*** object of the response, allowing you to match a sent message to a returned message result status.
                            example: clientId-3023
                            type: string
                          mobileNumber:
                            description: A recipient mobile number, using the international E164 (without the plus) format.
                            example: "27444444444"
                            type: string
                        required:
                          - mobileNumber
                        title: messageRecipientDetails
                        type: object
                      maxItems: 1000
                      minItems: 1
                      type: array
                    scheduledTime:
                      description: |
                        ***Optional*** - The date and time that an SMS should be delivered. If not specified, or is set for a date/time prior to the current date/time, the SMS message will be sent immediately.

                        If specified, this value should have the format YYYYMMDDHHmm.
                      example: "201712251430"
                      type: string
                  required:
                    - message
                    - recipients
                  title: messageDetails
                  type: object
                type: array
            title: multiMessageDetails
            type: object
      produces:
        - application/json
      responses:
        "200":
          description: OK
          schema:
            example:
              messages:
                - message: Happy holidays from all at TelAmeriCorp.
                  recipients:
                    - acceptError: ""
                      accepted: true
                      apiMessageId: 2316
                      clientMessageId: clientId-3023
                      creditCost: 1
                      mobileNumber: "27444444444"
                      newCreditBalance: 188.6
                      scheduledTime: "201712251430"
                    - acceptError: ""
                      accepted: true
                      apiMessageId: 2317
                      clientMessageId: null
                      creditCost: 1
                      mobileNumber: "27555555555"
                      newCreditBalance: 187.6
                      scheduledTime: "201712251430"
                    - acceptError: BADDEST
                      accepted: false
                      apiMessageId: null
                      clientMessageId: clientId-3024
                      creditCost: 0
                      mobileNumber: "276666666666"
                      newCreditBalance: 187.6
                      scheduledTime: null
                - message: TelAmeriCorp flash sale - call now for details
                  recipients:
                    - acceptError: ""
                      accepted: true
                      apiMessageId: 2318
                      clientMessageId: clientId-0015
                      creditCost: 1
                      mobileNumber: "27333333333"
                      newCreditBalance: 186.6
                      scheduledTime: "201801010900"
                    - acceptError: ""
                      accepted: true
                      apiMessageId: 2319
                      clientMessageId: null
                      creditCost: 1
                      mobileNumber: "27222222222"
                      newCreditBalance: 185.6
                      scheduledTime: "201801010900"
              statusCode: 200
              timeStamp: "20170117054658978"
              version: "1.0"
            properties:
              messages:
                description: An array of messageDetailsResponse objects
                items:
                  properties:
                    message:
                      description: |
                        The message text that was sent.
                      type: string
                    recipients:
                      description: An array of messageRecipientResponse objects
                      items:
                        example:
                          acceptError: ""
                          accepted: true
                          apiMessageId: 2316
                          clientMessageId: clientId-3023
                          creditCost: 1
                          mobileNumber: "27444444444"
                          newCreditBalance: 188.6
                          scheduledTime: "201712251430"
                        properties:
                          acceptError:
                            description: |
                              If the ***accepted*** value is **false**, this will contain the reason that delivery to the recipient was declined by the API. If the recipient was accepted, this value will be blank. Possible values-
                                | Value | Description |
                                |-------|-------------|
                                |INSUFFICIENT&nbsp;CREDITS | The User Account has insufficient credits to send the message |
                                |ACCOUNTLOCKED | The specified User Account is locked
                                |TRIALNOT2SELF | Trial Account Restriction – Message not to own number. <a href="https://support.winsms.co.za/trial-account-restrictions/" target="_blank">More Info</a> |
                                |TOOLONG | The <a href="https://en.wikipedia.org/wiki/GSM_03.38#GSM_7-bit_default_alphabet_and_extension_table_of_3GPP_TS_23.038_/_GSM_03.38" target="_blank">GSM 7-bit encoded</a> message length exceeded 918 characters |
                                |BADDEST | An invalid mobile number was supplied, or the recipient has been blacklisted from receiving messages |
                                |OPTEDOUT | The recipient has opted out from receiving any further messages from the user |
                                |WASPADNC | The number is on the WASPA Do Not Contact List (DNC).<br>If you are sending transactional messages then you can bypass the DNC list. <a href="https://zasupport.winsms.co.za/portal/en/kb/articles/marketing-vs-transactional-sms/" target="_blank">Read this article</a> for instructions. |
                                | &nbsp; | &nbsp; |
                            example: BADDEST
                            type: string
                          accepted:
                            description: |
                              A boolean value indicating whether the API accepted the recipient for SMS delivery. This will be **false** If you have insufficient credits or the recipient mobile number supplied is not valid.
                            example: true
                            type: boolean
                          apiMessageId:
                            description: |
                              The WinSMS Message Id assigned to the specific message recipient. This Id can be used to obtain the status of the message, and to delete the message if it was scheduled. If the API did not accept the recipient for delivery, the value will be **null**.
                            example: 2316
                            type: integer
                          clientMessageId:
                            description: |
                              If the optional ***clientMessageId*** value was specified in the recipient object for the recipient, it will be returned here. If not, ***clientMessageId*** will be **null**.
                            example: clientId-3023
                            type: string
                          creditCost:
                            description: |
                              The number of credits deducted from your account for the SMS to this recipient.

                              The credit cost is based on the destination country of the recipient and the length (number of segments) of the message.

                              This credit cost will be reimbursed if the message is scheduled and subsequently deleted.

                              If the recipient is not accepted for delivery, the ***creditCost*** value will be **null**.
                            example: 1.3
                            format: double
                            type: number
                          mobileNumber:
                            description: |
                              The mobile number specified as the ***mobileNumber*** value of the recipient object of the request.
                            example: "27824444444"
                            type: string
                          newCreditBalance:
                            description: |
                              The number of WinSMS credits remaining in your account after processing this recipient.
                            example: 188.6
                            format: double
                            type: number
                          scheduledTime:
                            description: |
                              The date and time that the message was scheduled for delivery to the recipient.

                              If no ***scheduledTime*** value was specified in the request, or the recipient was not accepted for delivery, this value will be **null**.
                            example: "201712251430"
                            type: string
                        title: messageRecipientResponse
                        type: object
                      maxItems: 1000
                      minItems: 1
                      type: array
                  title: messageDetailsResponse
                  type: object
                type: array
              statusCode:
                description: The http status code returned - reflected in the body for convenience
                type: integer
              timeStamp:
                description: The date/time the request was processed, in the format YYYYMMDDhhmmssSSS
                type: string
              version:
                description: The current version of the API of the endpoint that was called
                type: string
            title: multiMessageResponse
            type: object
        "400":
          description: Bad Request
          examples:
            application/json:
              errorMessage: Invalid JSON payload received
              statusCode: 400
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "401":
          description: Unauthorized
          examples:
            application/json:
              errorMessage: The 'AUTHORIZATION' header was not found. Set the 'AUTHORIZATION' request header to your WinSMS API Key
              statusCode: 401
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "404":
          description: Not found
          examples:
            application/json:
              errorMessage: The resource requested does not exist. Please verify the path, spelling, and capitalisation
              statusCode: 404
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "405":
          description: Method Not Allowed
          examples:
            application/json:
              errorMessage: Request method should be set to 'POST', not 'GET'.
              statusCode: 405
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "413":
          description: Payload Too Large
          examples:
            application/json:
              errorMessage: "Request POST data is: 205kb. The maximum POST size allowed is 200kb."
              statusCode: 413
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "415":
          description: Unsupported Media Type
          examples:
            application/json:
              errorMessage: Request content-type should be set to 'application/json', not 'text/plain'.
              statusCode: 415
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "422":
          description: Unprocessable Entity
          examples:
            application/json:
              errorMessage: There is an error in the 'recipients' array of one or more messageDetails objects.
              statusCode: 422
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "500":
          description: Internal Server Error
          examples:
            application/json:
              errorMessage: An unknown error has occurred - authorising API Key
              statusCode: 500
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
      summary: Send multiple different SMS messages
      tags:
        - sms
  /sms/outgoing/status:
    post:
      description: |
        Get a list of previously submitted SMS message delivery statuses.

        Post an array of API Message Ids received from the ***/sms/outgoing/send*** endpoint.
      operationId: smsStatus
      parameters:
        - description: |
            An array of WinSMS API Ids received after submitting messages to the ***/sms/outgoing/send*** endpoint.

            A maximum of 1000 API Ids can be supplied in a single request.
          in: body
          name: messageStatusRequest
          required: true
          schema:
            example:
              - 2316
              - 2317
            items:
              type: integer
            maxItems: 1000
            minItems: 1
            type: array
      produces:
        - application/json
      responses:
        "200":
          description: OK
          schema:
            example:
              messageStatuses:
                - apiMessageId: 2316
                  creditCost: 1
                  mobileNumber: "27444444444"
                  statusDelivered: true
                  statusErrorCode: 0
                  statusTime: "201712251431"
                - apiMessageId: 2317
                  creditCost: 1
                  mobileNumber: "27555555555"
                  statusDelivered: false
                  statusErrorCode: BADDEST
                  statusTime: "201712251432"
              statusCode: 200
              timeStamp: "20170117054658978"
              version: "1.0"
            properties:
              messageStatuses:
                description: |
                  An array of ***messageStatus*** objects detailing the delivery status of each message
                items:
                  example:
                    apiMessageId: 2316
                    creditCost: 1
                    mobileNumber: "27444444444"
                    statusDelivered: true
                    statusErrorCode: 0
                    statusTime: "201712251431"
                  properties:
                    apiMessageId:
                      description: The WinSMS API Message Id identifying the SMS message.
                      example: 2316
                      type: integer
                    creditCost:
                      description: |
                        The number of credits deducted from your account for the SMS to this recipient.


                        If delivery to the recipient is unsuccessful, under certain conditions, this may be 0.
                      example: 1.3
                      format: double
                      type: number
                    mobileNumber:
                      description: The mobile number of the recipient of the SMS message, using the international E164 (without the plus) format
                      example: "27824444444"
                      type: string
                    statusDelivered:
                      description: A boolean value indicating whether an SMS message was successfully delivered to the recipient's mobile number
                      example: true
                      type: boolean
                    statusErrorCode:
                      description: |
                        If the SMS message was successfully delivered, this value will be blank.
                        If the ***statusDelivered*** value is false, this will contain a string indicating the current status of the SMS message. Possible values-
                        | Value | Description | Type |
                        |-------|-------------|------|
                        | SENT| The message has been sent to the recipient, but no delivery report has been received | Temporary |
                        | NOTFOUND | Either an incorrect MessageID was sent in the request, or the message was sent more than 90 days previously | Permanent |
                        | INQUEUE | Message is queued for sending | Temporary |
                        | SENDINGFAILED | The message was not transmitted, due to e.g. an invalid destination number or insufficient credits | Permanent |
                        | FAILED | The message was sent but could not be delivered to the recipient due to e.g. no such subscriber, subscriber's phone offline | Permanent |
                      example: FAILED
                      type: string
                    statusTime:
                      description: |
                        The date and time of the last status update for this message, in the format YYYYMMDDHHmm.

                        If the message was delivered (**statusDelivered = true**) then this is a final status time. If the message is still awaiting delivery, this time might change when updates are received.
                      example: "201712251431"
                      type: string
                  title: messageStatus
                  type: object
                maxItems: 1000
                minItems: 1
                type: array
              statusCode:
                description: The http status code returned - reflected in the body for convenience
                type: integer
              timeStamp:
                description: The date/time the request was processed, in the format YYYYMMDDhhmmssSSS
                type: string
              version:
                description: The current version of the API of the endpoint that was called
                type: string
            title: messageStatusResponse
            type: object
        "400":
          description: Bad Request
          examples:
            application/json:
              errorMessage: Invalid JSON payload received
              statusCode: 400
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "401":
          description: Unauthorized
          examples:
            application/json:
              errorMessage: The 'AUTHORIZATION' header was not found. Set the 'AUTHORIZATION' request header to your WinSMS API Key
              statusCode: 401
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "404":
          description: Not found
          examples:
            application/json:
              errorMessage: The resource requested does not exist. Please verify the path, spelling, and capitalisation
              statusCode: 404
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "405":
          description: Method Not Allowed
          examples:
            application/json:
              errorMessage: Request method should be set to 'POST', not 'GET'.
              statusCode: 405
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "413":
          description: Payload Too Large
          examples:
            application/json:
              errorMessage: "Request POST data is: 205kb. The maximum POST size allowed is 200kb."
              statusCode: 413
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "415":
          description: Unsupported Media Type
          examples:
            application/json:
              errorMessage: Request content-type should be set to 'application/json', not 'text/plain'.
              statusCode: 415
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "422":
          description: Unprocessable Entity
          examples:
            application/json:
              errorMessage: At least one non-numeric api Id was supplied in the apiIds array.
              statusCode: 422
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "500":
          description: Internal Server Error
          examples:
            application/json:
              errorMessage: An unknown error has occurred - authorising API Key
              statusCode: 500
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
      summary: Get SMS delivery statuses
      tags:
        - sms
  /sms/scheduled:
    get:
      description: |
        Get a list of all scheduled SMS messages that have not yet been sent.

        Only the first 100 scheduled messages will be returned if no ***offset*** and ***limit*** parameters are specified.
      operationId: getScheduledMessages
      parameters:
        - default: 0
          description: |
            ***Optional*** - The number of items to skip before starting to return results. Default 0. Minimum 0.
          in: query
          minimum: 0
          name: offset
          required: false
          type: integer
        - default: 100
          description: |
            ***Optional*** - The number of items to return. Default 100. Minimum 1. Maximum 1000.
          in: query
          maximum: 1000
          minimum: 1
          name: limit
          required: false
          type: integer
      produces:
        - application/json
      responses:
        "200":
          description: OK
          schema:
            example:
              resultsLimit: 100
              resultsOffset: 3400
              resultsTotalAvailable: 3402
              scheduledMessages:
                - apiMessageId: 2316
                  creditCost: 1
                  mobileNumber: "27444444444"
                  scheduledSendTime: "201712251430"
                  submitTime: "201710220850"
                - apiMessageId: 2317
                  creditCost: 1
                  mobileNumber: "27555555555"
                  scheduledSendTime: "201712251430"
                  submitTime: "201710220850"
              statusCode: 200
              timeStamp: "20170117054658978"
              version: "1.0"
            properties:
              resultsLimit:
                description: |
                  The number of items returned in the results. This is the value specified in the ***limit*** parameter sent to the endpoint. If the parameter was not specified, this defaults to 100.
                type: integer
              resultsOffset:
                description: |
                  The number of items skipped before the results were returned. This is the value specified in the ***offset*** parameter sent to the endpoint. If the parameter was not specified, this defaults to 0.
                type: integer
              resultsTotalAvailable:
                description: |
                  The total number of results available for retrieval. The ***offset*** and ***limit*** properties specify which of the total available results have been returned.
                type: integer
              scheduledMessages:
                description: |
                  An array of ***scheduledMessage*** objects containing properties of each unsent scheduled message.
                items:
                  example:
                    apiMessageId: 2316
                    creditCost: 1
                    mobileNumber: "27444444444"
                    scheduledSendTime: "201712251430"
                    submitTime: "201710220850"
                  properties:
                    apiMessageId:
                      description: The WinSMS API Message Id identifying the SMS message.
                      example: 2316
                      type: integer
                    creditCost:
                      description: |
                        The number of credits deducted from your account for the SMS to this recipient.

                        This is the number of credits that will be refunded if you delete this scheduled message.
                      example: 1.3
                      format: double
                      type: number
                    mobileNumber:
                      description: The mobile number of the recipient of the SMS message, using the international E164 (without the plus) format
                      example: "27824444444"
                      type: string
                    scheduledSendTime:
                      description: The date and time the message is scheduled to be delivered to the recipient, in the format YYYYMMDDHHmm.
                      example: "201812250930"
                      type: string
                    submitTime:
                      description: The date and time the message was originally submitted for scheduled delivery, in the format YYYYMMDDHHmm.
                      example: "201712251431"
                      type: string
                  title: scheduledMessage
                  type: object
                maxItems: 1000
                minItems: 1
                type: array
              statusCode:
                description: The http status code returned - reflected in the body for convenience
                type: integer
              timeStamp:
                description: The date/time the request was processed, in the format YYYYMMDDhhmmssSSS
                type: string
              version:
                description: The current version of the API of the endpoint that was called
                type: string
            title: scheduledMessageResponse
            type: object
        "401":
          description: Unauthorized
          examples:
            application/json:
              errorMessage: The 'AUTHORIZATION' header was not found. Set the 'AUTHORIZATION' request header to your WinSMS API Key
              statusCode: 401
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "404":
          description: Not found
          examples:
            application/json:
              errorMessage: The resource requested does not exist. Please verify the path, spelling, and capitalisation
              statusCode: 404
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "405":
          description: Method Not Allowed
          examples:
            application/json:
              errorMessage: Request method should be set to 'GET', not 'PUT'.
              statusCode: 405
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "422":
          description: Unprocessable Entity
          examples:
            application/json:
              errorMessage: The offset parameter must be a number greater than or equal to 0.
              statusCode: 422
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "500":
          description: Internal Server Error
          examples:
            application/json:
              errorMessage: An unknown error has occurred - authorising API Key
              statusCode: 500
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
      summary: Get a list of scheduled SMS messages
      tags:
        - sms
  /sms/scheduled/delete:
    post:
      description: |
        Delete a list of previously scheduled SMS messages that have not yet been sent.

        Credits originally deducted for each SMS message will be refunded to your account upon successful deletion.
      operationId: deleteScheduledMessages
      parameters:
        - description: |
            An array of WinSMS API Ids received after submitting scheduled messages to the ***/sms/outgoing/send*** endpoint.<br> A maximum of 1000 API Ids can be supplied in a single request.
          in: body
          name: messageDeleteRequest
          required: true
          schema:
            example:
              - 2316
              - 2317
            items:
              type: integer
            maxItems: 1000
            minItems: 1
            type: array
      produces:
        - application/json
      responses:
        "200":
          description: OK
          schema:
            example:
              deletedMessageStatuses:
                - apiMessageId: 2316
                  creditCost: 1
                  deleteError: ""
                  deleted: true
                  mobileNumber: "27444444444"
                - apiMessageId: 2317
                  creditCost: 0
                  deleteError: NOTFOUND
                  deleted: false
                  mobileNumber: "27555555555"
              statusCode: 200
              timeStamp: "20170117054658978"
              version: "1.0"
            properties:
              deletedMessageStatuses:
                description: |
                  An array of ***deletedMessageStatus*** objects detailing the deleted status of each message requested for deletion.
                items:
                  example:
                    apiMessageId: 2316
                    creditCost: 1
                    deleteError: ""
                    deleted: true
                    mobileNumber: "27444444444"
                  properties:
                    apiMessageId:
                      description: |
                        The WinSMS API Message Id identifying the SMS message.
                      example: 2316
                      type: integer
                    creditCost:
                      description: |
                        The number of credits refunded to your account after deleting the scheduled message.

                        If the deletion was unsuccessful, this value will be 0.
                      example: 1.3
                      format: double
                      type: number
                    deleteError:
                      description: |
                        If the ***deleted*** value is false, this will contain an error code indicating the reason for the failure. If the scheduled SMS message was successfully deleted, this value will be blank.
                      example: NOTFOUND
                      type: string
                    deleted:
                      description: |
                        A boolean value indicating whether a scheduled SMS message was successfully deleted
                      example: true
                      type: boolean
                    mobileNumber:
                      description: |
                        The mobile number of the recipient of the SMS message, using the international E164 (without the plus) format
                      example: "27824444444"
                      type: string
                  title: deletedMessageStatus
                  type: object
                maxItems: 1000
                minItems: 1
                type: array
              statusCode:
                description: The http status code returned - reflected in the body for convenience
                type: integer
              timeStamp:
                description: The date/time the request was processed, in the format YYYYMMDDhhmmssSSS
                type: string
              version:
                description: The current version of the API of the endpoint that was called
                type: string
            title: deleteScheduledResponse
            type: object
        "400":
          description: Bad Request
          examples:
            application/json:
              errorMessage: Invalid JSON payload received
              statusCode: 400
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "401":
          description: Unauthorized
          examples:
            application/json:
              errorMessage: The 'AUTHORIZATION' header was not found. Set the 'AUTHORIZATION' request header to your WinSMS API Key
              statusCode: 401
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "404":
          description: Not found
          examples:
            application/json:
              errorMessage: The resource requested does not exist. Please verify the path, spelling, and capitalisation
              statusCode: 404
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "405":
          description: Method Not Allowed
          examples:
            application/json:
              errorMessage: Request method should be set to 'POST', not 'GET'.
              statusCode: 405
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "413":
          description: Payload Too Large
          examples:
            application/json:
              errorMessage: "Request POST data is: 205kb. The maximum POST size allowed is 200kb."
              statusCode: 413
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "415":
          description: Unsupported Media Type
          examples:
            application/json:
              errorMessage: Request content-type should be set to 'application/json', not 'text/plain'.
              statusCode: 415
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "422":
          description: Unprocessable Entity
          examples:
            application/json:
              errorMessage: At least one non-numeric api Id was supplied in the apiIds array.
              statusCode: 422
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "500":
          description: Internal Server Error
          examples:
            application/json:
              errorMessage: An unknown error has occurred - authorising API Key
              statusCode: 500
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
      summary: Delete scheduled SMS messages and refund credits
      tags:
        - sms
  /subaccounts:
    get:
      description: Get a list of all the Sub Accounts owned by the Main Account.
      operationId: getSubAccounts
      produces:
        - application/json
      responses:
        "200":
          description: OK
          schema:
            example:
              statusCode: 200
              subAccounts:
                - accountNumber: 58324
                  creditBalance: 201.4
                  firstName: Jon
                  loginName: jon@castleblack.com
                  surname: Snow
                - accountNumber: 98676
                  creditBalance: 1936
                  firstName: Daenerys
                  loginName: khaleesi
                  surname: Targaryen
              timeStamp: "20170117054658978"
              version: "1.0"
            properties:
              statusCode:
                description: The http status code returned - reflected in the body for convenience
                type: integer
              subAccounts:
                description: |
                  An array of ***subAccount*** objects containing properties of each Sub Account owned by the Main Account.
                items:
                  example:
                    accountNumber: 58324
                    creditBalance: 201.4
                    firstName: Jon
                    loginName: jon@castleblack.com
                    surname: Snow
                  properties:
                    accountNumber:
                      description: |
                        The WinSMS account number of the Sub Account. This is supplied as an integer, without the leading 'W' displayed in the WinSMS Client Zone.
                      example: 58324
                      type: integer
                    creditBalance:
                      description: |
                        The remaining credit balance for the Sub Account.
                      example: 201.4
                      type: number
                    firstName:
                      description: |
                        The first name of the user that the Sub Account is registered to.
                      example: Jon
                      type: string
                    loginName:
                      description: |
                        The login name of the user that the Sub Account is registered to.
                      example: jon@castleblack.com
                      type: string
                    surname:
                      description: |
                        The surname of the user that the Sub Account is registered to.
                      example: Snow
                      type: string
                  title: subAccount
                  type: object
                type: array
              timeStamp:
                description: The date/time the request was processed, in the format YYYYMMDDhhmmssSSS
                type: string
              version:
                description: The current version of the API of the endpoint that was called
                type: string
            title: subAccountsResponse
            type: object
        "401":
          description: Unauthorized
          examples:
            application/json:
              errorMessage: The 'AUTHORIZATION' header was not found. Set the 'AUTHORIZATION' request header to your WinSMS API Key
              statusCode: 401
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "404":
          description: Not found
          examples:
            application/json:
              errorMessage: The resource requested does not exist. Please verify the path, spelling, and capitalisation
              statusCode: 404
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "405":
          description: Method Not Allowed
          examples:
            application/json:
              errorMessage: Request method should be set to 'GET', not 'PUT'.
              statusCode: 405
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
        "500":
          description: Internal Server Error
          examples:
            application/json:
              errorMessage: An unknown error has occurred - authorising API Key
              statusCode: 500
              timeStamp: "20170120152253514"
              version: "1.0"
          schema:
            $ref: "#/definitions/errorDetails"
      summary: Get a list of all Sub Accounts.
      tags:
        - subaccounts
definitions:
  errorDetails:
    example:
      errorMessage: |
        The resource requested does not exist. Please verify the path, spelling, and capitalisation
      statusCode: 404
      timeStamp: "20170120152253514"
      version: "1.0"
    properties:
      errorMessage:
        description: |
          A plain text description of the error that occurred, and possible solutions if available. 
        type: string
      statusCode:
        description: |
          The http status code returned - reflected in the body for convenience
        type: integer
      timeStamp:
        description: |
          The date/time the request was processed, in the format YYYYMMDDhhmmssSSS
        type: string
      version:
        description: |
          The current version of the API of the endpoint that was called
        type: string
    title: errorDetails
    type: object
