openapi: 3.0.3
info:
  description: >-
    The Retarus SMS for Applications REST API is a service to send SMS and
    lookup the status.


    To obtain a test account for this service or any of our other SMS services,
    please contact Retarus.
  contact:
    name: Retarus
    url: https://www.retarus.com/
    email: info@retarus.com
  termsOfService: https://www.retarus.com/us/legal-disclaimer/
  version: v1.0.0
  title: SMS for Applications REST API
servers:
  - url: https://sms4a.de2.retarus.com/rest/v1
    description: Primary data center
  - url: https://sms4a.de1.retarus.com/rest/v1
    description: Secondary data center
  - url: https://sms4a.eu.retarus.com/rest/v1
    description: HA endpoint - only to send SMS
security:
  - httpBasicAuth: []
tags:
  - name: SMS Jobs
  - name: SMS Status
  - name: Version
paths:
  /jobs:
    post:
      tags:
        - SMS Jobs
      summary: Send SMS Job.
      description: >-
        Send one or more SMS with one or more recipients each. The response
        contains the job ID (jobId) of your new SMS job.
      operationId: postJob
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobRequest'
            examples:
              minimal:
                $ref: '#/components/examples/SMSJobRequestMinimal'
              multipleRecipients:
                $ref: '#/components/examples/SMSJobRequestMulitpleRecipients'
              multipleSMS:
                $ref: '#/components/examples/SMSJobRequestMulitpleSMS'
              complete:
                $ref: '#/components/examples/SMSJobRequestComplete'
      responses:
        '201':
          description: Job successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
              example:
                jobId: J.20221116-102407.583-0lajfsfmoXIZJO93PQ
        '400':
          description: Invalid JobRequest-data (qos, encoding, ..).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithDetails'
              example:
                code: 400
                message: 'Wrong qos: PRIORITY'
                details: root.options.qos
        '401':
          description: Authentication failed.
        '409':
          description: Duplicate job (detected by enabled duplicate-detection).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 409
                message: Duplicate job.
        '422':
          description: Invalid JobRequest-data (invalid chars, no messages, ..).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseWithDetails'
              example:
                code: 422
                message: >-
                  Invalid Characters in Message[001/001] 'ショートメッセージサービス' for
                  encoding 'GSM7' and InvalidCharacters 'REFUSE'.
                details: root.messages[0]
        '429':
          description: Too many requests
        default:
          description: Other error response.
    get:
      tags:
        - SMS Jobs
      summary: Get all jobs for given criteria.
      description: >-
        Get a list of job IDs for a specified time period and corresponding to
        the other optionla filters.
      operationId: listJobs
      parameters:
        - name: jobIdsOnly
          in: query
          description: Return only jobIDs. Currently only 'true' is supported.
          required: true
          schema:
            type: boolean
            default: true
        - name: fromTs
          in: query
          description: >-
            From timestamp (ISO-8601). The interval between fromTs and toTs can
            be a maximum of 30 days.
          required: false
          schema:
            type: string
            format: date-time
            example: 2022-06-13T00:00+02:00
        - name: toTs
          in: query
          description: >-
            To timestamp (ISO-8601). The interval between fromTs and toTs can be
            a maximum of 30 days.
          required: false
          schema:
            type: string
            format: date-time
            example: 2022-06-20T00:00+02:00
        - name: open
          in: query
          description: Return only open jobs.
          required: false
          schema:
            type: boolean
            default: false
        - name: offset
          in: query
          description: >-
            Parameter used for pagination. Retrieve a subset of records starting
            with the offset value.
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
            format: int64
        - name: limit
          in: query
          description: Limit number of results returned. Value must be between 0 and 1000.
          required: false
          schema:
            type: integer
            default: 100
            maximum: 1000
            minimum: 1
            format: int64
      responses:
        '200':
          description: List jobs successful.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobReport'
        '400':
          description: Invalid request-parameter.
        '401':
          description: Authentication failed.
        '500':
          description: Can't list jobs.
  /jobs/{jobId}:
    get:
      tags:
        - SMS Jobs
      summary: Get job status
      description: >-
        Get the job status and the list SMS IDs for the job.  In order to get
        the individual SMS status for all SMS's of a job, use the SMS status 
        endpoint /sms with the corresponding jobId parameter - eg
        /sms?jobId=J.20180620-085038.561-0jimrdkk7SOILYBNMK
      operationId: getJob
      parameters:
        - name: jobId
          in: path
          description: The Retarus job ID.
          required: true
          schema:
            type: string
            pattern: J\..{18,38}
            example: J.20180620-085038.561-0jimrdkk7SOILYBNMK
      responses:
        '200':
          description: Get report for job ID successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobReport'
        '400':
          description: No jobID given.
        '401':
          description: Authentication failed.
        '500':
          description: Can't query report for jobId.
  /sms:
    get:
      tags:
        - SMS Status
      summary: Get status for all recipients of a job.
      description: Get the individual SMS status for all SMS's of a job
      operationId: listRecipients
      parameters:
        - name: jobId
          in: query
          description: The Retarus job ID.
          required: true
          schema:
            type: string
            pattern: J\..{18,38}
            example: J.20180620-085038.561-0jimrdkk7SOILYBNMK
      responses:
        '200':
          description: Get report for all recipients of job ID successful.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecipientReport'
        '400':
          description: No job ID given.
        '401':
          description: Authentication failed.
        '404':
          description: Invalid request
        '500':
          description: Can't query report for jobID
  /version:
    get:
      tags:
        - Version
      summary: Get version information
      description: Get the version informantion for the API.
      operationId: get
      parameters: []
      responses:
        '200':
          description: Get version info successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionInfoResponse'
components:
  securitySchemes:
    httpBasicAuth:
      type: http
      scheme: basic
  schemas:
    JobResponse:
      type: object
      properties:
        jobId:
          type: string
          readOnly: true
    JobRequest:
      type: object
      required:
        - messages
      properties:
        options:
          $ref: '#/components/schemas/Options'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
    Message:
      type: object
      title: SMS messages
      required:
        - recipients
        - text
      properties:
        text:
          type: string
          description: foo
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
    Options:
      type: object
      properties:
        src:
          type: string
          example: retarus
          pattern: (\+|)[0-9]{1,20}|[a-zA-Z0-9\x20\p{Punct}]{1,11}
          description: The Sender ID displayed to recipient.
        encoding:
          type: string
          enum:
            - STANDARD
            - UTF-16
        billcode:
          type: string
          description: Max. 70 characters.
        statusRequested:
          type: boolean
          description: Delivery notification requested.
        flash:
          type: boolean
        customerRef:
          type: string
          description: Recommended max. 64 characters.
        validityMin:
          type: integer
          format: int64
          description: >-
            Validity of the SMS in minutes. When 0 the provider’s default value
            is used. Otherwise, values must be between 5 and 2880 minutes.
        maxParts:
          type: integer
          format: int32
          description: >-
            Maximum allowed parts in a multi-part message. Values must be
            between 1 and 20. Longer messages are truncated.
        invalidCharacters:
          type: string
          description: Define how to handle invalid characters in SMS.
          enum:
            - REFUSE
            - REPLACE
            - TO_UTF16
            - TRANSLITERATE
        qos:
          type: string
          description: Quality of Service.
          enum:
            - EXPRESS
            - NORMAL
        jobPeriod:
          type: string
          format: date-time
          example: '2018-07-09T11:25:24.683+02:00'
          description: >-
            Timestamp to schedule when to start processing the SMS Job
            (iso-8601).
        duplicateDetection:
          type: boolean
        blackoutPeriods:
          type: array
          items:
            type: string
            example: 2018-07-09T10:25:24.683+02:00/2018-07-09T11:25:24.683+02:00
            description: >-
              Time periods in which no SMS is delivered (iso-8601). SMS will be
              scheduled to be sent at the end of the blackout period.
    Recipient:
      type: object
      required:
        - dst
      properties:
        dst:
          type: string
        customerRef:
          type: string
          description: >-
            Recommended max. 64 characters. Recipient mobile phone number used
            as default.
        blackoutPeriods:
          type: array
          items:
            type: string
            example: 2018-07-09T10:25:24.683+02:00/2018-07-09T11:25:24.683+02:00
            description: >-
              Time periods in which no SMS is delivered (iso-8601). SMS will be
              scheduled to be sent at the end of the blackout period.
    JobReport:
      type: object
      properties:
        jobId:
          type: string
          readOnly: true
          example: J.20220928-125820.020-0l8likuetGNOTM4A4U
        src:
          type: string
          description: Sender ID.
          readOnly: true
          example: retarus
        encoding:
          type: string
          readOnly: true
          enum:
            - standard
            - utf-16
        billcode:
          type: string
          readOnly: true
          example: Campaign123
        statusRequested:
          type: boolean
          description: Delivery notification requested.
          readOnly: true
        flash:
          type: boolean
          readOnly: true
          example: false
        validityMin:
          type: integer
          format: int64
          description: Validity of the SMS in minutes.
          readOnly: true
          example: 2880
        customerRef:
          type: string
          description: Recommended max. 64 characters.
          readOnly: true
          example: 'InternalID: ABC1234 Tag: Marketing'
        qos:
          type: string
          description: Quality of Service.
          readOnly: true
          enum:
            - EXPRESS
            - NORMAL
          example: NORMAL
        receiptTs:
          type: string
          format: date-time
          example: '2022-09-01T10:25:00.000Z'
          description: >-
            Timestamp indicating when the job was received by Retarus
            (iso-8601).
          readOnly: true
        finishedTs:
          type: string
          format: date-time
          example: '2022-09-30T10:25:00.000Z'
          description: >-
            Timestamp indicating when the SMS received its final status
            (iso-8601).
          readOnly: true
        recipientIds:
          type: array
          readOnly: true
          items:
            type: string
          example:
            - S.20220928-125820.022-0l8likueyRB3CT8FTG
    RecipientReport:
      type: object
      properties:
        smsId:
          type: string
          readOnly: true
          example: S.20220928-125820.022-0l8likueyRB3CT8FTG
        dst:
          type: string
          description: Recipient’s mobile phone number.
          readOnly: true
          example: '+4917600000000'
        processStatus:
          type: string
          description: Current process status (see SMS Outbound Status Codes).
          readOnly: true
          example: DONE
        status:
          type: string
          description: Status (see SMS Outbound Status Codes).
          readOnly: true
          example: SUC_FIN
        customerRef:
          type: string
          description: Recommended max. 64 characters.
          readOnly: true
          example: 'TransactionId: ABC123'
        reason:
          type: string
          readOnly: true
          example: >-
            message_state:DELIVERED [00000002] (Final) (Message is delivered to
            destination.)
        sentTs:
          type: string
          format: date-time
          example: '2022-09-28T10:58:30.022Z'
          description: Timestamp when the SMS was sent (iso-8601).
          readOnly: true
        finishedTs:
          type: string
          format: date-time
          example: '2022-09-28T10:59:34.150Z'
          description: >-
            Timestamp which indicates when the SMS received its final status
            (iso-8601).
          readOnly: true
    VersionInfoResponse:
      type: object
      properties:
        buildNumber:
          type: integer
          format: int32
          readOnly: true
        buildTimestamp:
          type: string
          readOnly: true
        majorVersion:
          type: integer
          format: int32
          readOnly: true
        minorVersion:
          type: integer
          format: int32
          readOnly: true
        versionInfo:
          type: string
          readOnly: true
        message:
          type: string
          readOnly: true
    ErrorResponse:
      properties:
        code:
          type: integer
        message:
          type: string
    ErrorResponseWithDetails:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
      properties:
        details:
          type: string
  examples:
    SMSJobRequestMinimal:
      summary: Send one SMS message
      description: >-
        Send just one SMS - one message to one recipient - using default account
        options
      value:
        messages:
          - text: Your access code is ABC1234
            recipients:
              - dst: '+4917600000000'
    SMSJobRequestMulitpleRecipients:
      summary: Send one SMS message to multiple recipients
      description: >-
        Send one message to 3 recipients - equals 3 SMS - using default account
        options
      value:
        messages:
          - text: Your summer vacation discount code is SUMMER22
            recipients:
              - dst: '+4917100000000'
              - dst: '+4917200000000'
              - dst: '+4917600000000'
    SMSJobRequestMulitpleSMS:
      summary: Send mutliple SMS messages
      description: >-
        Send 3 different messages, each to 1 recipient - equals 3 SMS - using
        default account options
      value:
        messages:
          - test: Your OPT access code is code is ABC123
            recipients:
              - dst: '+4917100000000'
          - test: Your OPT access code is code is DEF456
            recipients:
              - dst: '+4917200000000'
          - test: Your OPT access code is code is GHI789
            recipients:
              - dst: '+4917600000000'
    SMSJobRequestComplete:
      summary: Send SMS with all options
      description: Send one SMS using all options
      value:
        options:
          src: retarus
          encoding: STANDARD
          billcode: OTP
          statusRequested: true
          flash: true
          customerRef: 'TranscationID: ABC1234000'
          validityMin: 10
          maxParts: 3
          invalidCharacters: REPLACE
          qos: EXPRESS
          jobPeriod: '2023-04-26T15:30:00.000+02:00'
          duplicateDetection: true
          blackoutPeriods:
            - 2022-07-09T20:00:00.000+02:00/2022-07-10T07:00:00.000+02:00
        messages:
          - text: Your access code is ABC1234
            recipients:
              - dst: '+4917600000000'
                customerRef: 'TransactionID: ABC1234000 CustomerID: 123'
                blackoutPeriods:
                  - 2022-07-09T20:00:00.000+02:00/2022-07-10T07:00:00.000+02:00
