{
  "openapi": "3.1.0",
  "info": {
    "summary": "Send SMS and look up delivery status via REST.",
    "description": "The Retarus SMS for Applications REST API is a service to send SMS and lookup the status.\n\nTo 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 total number of recipients is limited to 3000 per job. 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/SMSJobRequestMultipleRecipients"
                },
                "multipleSMS": {
                  "$ref": "#/components/examples/SMSJobRequestMultipleSMS"
                },
                "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 optional 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",
              "examples": [
                "2022-06-13T00:00: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",
              "examples": [
                "2022-06-20T00:00: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}",
              "examples": [
                "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}",
              "examples": [
                "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 information 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",
            "examples": [
              "retarus"
            ],
            "pattern": "^(?:\\+?[0-9]{1,20}|[ -~]{1,11})$",
            "description": "The Sender ID displayed to the recipient. Use a phone number, or a text ID of up to 11 printable ASCII characters. Not all carriers support punctuation and other special characters."
          },
          "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",
            "examples": [
              "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",
              "examples": [
                "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",
              "examples": [
                "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,
            "examples": [
              "J.20220928-125820.020-0l8likuetGNOTM4A4U"
            ]
          },
          "src": {
            "type": "string",
            "description": "Sender ID.",
            "readOnly": true,
            "examples": [
              "retarus"
            ]
          },
          "encoding": {
            "type": "string",
            "readOnly": true,
            "enum": [
              "standard",
              "utf-16"
            ]
          },
          "billcode": {
            "type": "string",
            "readOnly": true,
            "examples": [
              "Campaign123"
            ]
          },
          "statusRequested": {
            "type": "boolean",
            "description": "Delivery notification requested.",
            "readOnly": true
          },
          "flash": {
            "type": "boolean",
            "readOnly": true,
            "examples": [
              false
            ]
          },
          "validityMin": {
            "type": "integer",
            "format": "int64",
            "description": "Validity of the SMS in minutes.",
            "readOnly": true,
            "examples": [
              2880
            ]
          },
          "customerRef": {
            "type": "string",
            "description": "Recommended max. 64 characters.",
            "readOnly": true,
            "examples": [
              "InternalID: ABC1234 Tag: Marketing"
            ]
          },
          "qos": {
            "type": "string",
            "description": "Quality of Service.",
            "readOnly": true,
            "enum": [
              "EXPRESS",
              "NORMAL"
            ],
            "examples": [
              "NORMAL"
            ]
          },
          "receiptTs": {
            "type": "string",
            "format": "date-time",
            "examples": [
              "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",
            "examples": [
              "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"
            },
            "examples": [
              [
                "S.20220928-125820.022-0l8likueyRB3CT8FTG"
              ]
            ]
          }
        }
      },
      "RecipientReport": {
        "type": "object",
        "properties": {
          "smsId": {
            "type": "string",
            "readOnly": true,
            "examples": [
              "S.20220928-125820.022-0l8likueyRB3CT8FTG"
            ]
          },
          "dst": {
            "type": "string",
            "description": "Recipient’s mobile phone number.",
            "readOnly": true,
            "examples": [
              "+4917600000000"
            ]
          },
          "processStatus": {
            "type": "string",
            "description": "Current process status (see SMS Outbound Status Codes).",
            "readOnly": true,
            "examples": [
              "DONE"
            ]
          },
          "status": {
            "type": "string",
            "description": "Status (see SMS Outbound Status Codes).",
            "readOnly": true,
            "examples": [
              "SUC_FIN"
            ]
          },
          "customerRef": {
            "type": "string",
            "description": "Recommended max. 64 characters.",
            "readOnly": true,
            "examples": [
              "TransactionID: ABC123"
            ]
          },
          "reason": {
            "type": "string",
            "readOnly": true,
            "examples": [
              "message_state:DELIVERED [00000002] (Final) (Message is delivered to destination.)"
            ]
          },
          "sentTs": {
            "type": "string",
            "format": "date-time",
            "examples": [
              "2022-09-28T10:58:30.022Z"
            ],
            "description": "Timestamp when the SMS was sent (iso-8601).",
            "readOnly": true
          },
          "finishedTs": {
            "type": "string",
            "format": "date-time",
            "examples": [
              "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"
                }
              ]
            }
          ]
        }
      },
      "SMSJobRequestMultipleRecipients": {
        "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"
                }
              ]
            }
          ]
        }
      },
      "SMSJobRequestMultipleSMS": {
        "summary": "Send multiple SMS messages",
        "description": "Send 3 different messages, each to 1 recipient - equals 3 SMS - using default account options",
        "value": {
          "messages": [
            {
              "text": "Your OPT access code is code is ABC123",
              "recipients": [
                {
                  "dst": "+4917100000000"
                }
              ]
            },
            {
              "text": "Your OPT access code is code is DEF456",
              "recipients": [
                {
                  "dst": "+4917200000000"
                }
              ]
            },
            {
              "text": "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": "TransactionID: 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"
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  }
}