SMS for Applications REST API (v1.0.0)

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.

Download OpenAPI description
sms4a-api.json
sms4a-api.yaml
Overview
URL

https://www.retarus.com/

Retarus

info@retarus.com

Terms of Service

Languages
Servers
Mock server

https://developers.retarus.com/_mock/sms/sms4a-api/

Primary data center

https://sms4a.de2.retarus.com/rest/v1/

Secondary data center

https://sms4a.de1.retarus.com/rest/v1/

HA endpoint - only to send SMS

https://sms4a.eu.retarus.com/rest/v1/

SMS Jobs

Operations

Send SMS Job.

Request

Send one or more SMS with one or more recipients each. The response contains the job ID (jobId) of your new SMS job.

Security
httpBasicAuth or oAuth or internalStagingOAuth
Bodyapplication/json
optionsobject(Options)
messagesArray of objects(SMS messages)required
messages[].​textstringrequired

foo

messages[].​recipientsArray of objects(Recipient)required
messages[].​recipients[].​dststringrequired
messages[].​recipients[].​customerRefstring

Recommended max. 64 characters. Recipient mobile phone number used as default.

messages[].​recipients[].​blackoutPeriodsArray of strings
Example: ["2018-07-09T10:25:24.683+02:00/2018-07-09T11:25:24.683+02:00"]
curl -i -X POST \
  -u <username>:<password> \
  https://developers.retarus.com/_mock/sms/sms4a-api/jobs \
  -H 'Content-Type: application/json' \
  -d '{
    "messages": [
      {
        "text": "Your access code is ABC1234",
        "recipients": [
          {
            "dst": "+4917600000000"
          }
        ]
      }
    ]
  }'

Responses

Job successfully created.

Bodyapplication/json
jobIdstringread-only
Response
application/json
{
  "jobId": "J.20221116-102407.583-0lajfsfmoXIZJO93PQ"
}

Get all jobs for given criteria.

Request

Get a list of job IDs for a specified time period and corresponding to the other optionla filters.

Security
httpBasicAuth or oAuth or internalStagingOAuth
Query
jobIdsOnlybooleanrequired

Return only jobIDs. Currently only 'true' is supported.

Default true
fromTsstring(date-time)

From timestamp (ISO-8601). The interval between fromTs and toTs can be a maximum of 30 days.

Example: fromTs=2022-06-13T00:00+02:00
toTsstring(date-time)

To timestamp (ISO-8601). The interval between fromTs and toTs can be a maximum of 30 days.

Example: toTs=2022-06-20T00:00+02:00
openboolean

Return only open jobs.

Default false
offsetinteger(int64)>= 0

Parameter used for pagination. Retrieve a subset of records starting with the offset value.

Default 0
limitinteger(int64)[ 1 .. 1000 ]

Limit number of results returned. Value must be between 0 and 1000.

Default 100
curl -i -X GET \
  -u <username>:<password> \
  'https://developers.retarus.com/_mock/sms/sms4a-api/jobs?fromTs=2022-06-13T00%3A00%2B02%3A00&jobIdsOnly=true&limit=100&offset=0&open=false&toTs=2022-06-20T00%3A00%2B02%3A00'

Responses

List jobs successful.

Bodyapplication/jsonArray [
jobIdstringread-only
Example: "J.20220928-125820.020-0l8likuetGNOTM4A4U"
srcstringread-only

Sender ID.

Example: "retarus"
encodingstringread-only
Enum"standard""utf-16"
billcodestringread-only
Example: "Campaign123"
statusRequestedbooleanread-only

Delivery notification requested.

flashbooleanread-only
Example: false
validityMininteger(int64)read-only

Validity of the SMS in minutes.

Example: 2880
customerRefstringread-only

Recommended max. 64 characters.

Example: "InternalID: ABC1234 Tag: Marketing"
qosstringread-only

Quality of Service.

Enum"EXPRESS""NORMAL"
Example: "NORMAL"
receiptTsstring(date-time)read-only

Timestamp indicating when the job was received by Retarus (iso-8601).

Example: "2022-09-01T10:25:00.000Z"
finishedTsstring(date-time)read-only

Timestamp indicating when the SMS received its final status (iso-8601).

Example: "2022-09-30T10:25:00.000Z"
recipientIdsArray of stringsread-only
Example: ["S.20220928-125820.022-0l8likueyRB3CT8FTG"]
]
Response
application/json
[
  {
    "jobId": "J.20220928-125820.020-0l8likuetGNOTM4A4U",
    "src": "retarus",
    "encoding": "standard",
    "billcode": "Campaign123",
    "statusRequested": true,
    "flash": false,
    "validityMin": 2880,
    "customerRef": "InternalID: ABC1234 Tag: Marketing",
    "qos": "NORMAL",
    "receiptTs": "2022-09-01T10:25:00.000Z",
    "finishedTs": "2022-09-30T10:25:00.000Z",
    "recipientIds": [ … ]
  }
]

Get job status

Request

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

Security
httpBasicAuth or oAuth or internalStagingOAuth
Path
jobIdstringJ\..{18,38}required

The Retarus job ID.

Example: J.20180620-085038.561-0jimrdkk7SOILYBNMK
curl -i -X GET \
  -u <username>:<password> \
  https://developers.retarus.com/_mock/sms/sms4a-api/jobs/J.20180620-085038.561-0jimrdkk7SOILYBNMK

Responses

Get report for job ID successful.

Bodyapplication/json
jobIdstringread-only
Example: "J.20220928-125820.020-0l8likuetGNOTM4A4U"
srcstringread-only

Sender ID.

Example: "retarus"
encodingstringread-only
Enum"standard""utf-16"
billcodestringread-only
Example: "Campaign123"
statusRequestedbooleanread-only

Delivery notification requested.

flashbooleanread-only
Example: false
validityMininteger(int64)read-only

Validity of the SMS in minutes.

Example: 2880
customerRefstringread-only

Recommended max. 64 characters.

Example: "InternalID: ABC1234 Tag: Marketing"
qosstringread-only

Quality of Service.

Enum"EXPRESS""NORMAL"
Example: "NORMAL"
receiptTsstring(date-time)read-only

Timestamp indicating when the job was received by Retarus (iso-8601).

Example: "2022-09-01T10:25:00.000Z"
finishedTsstring(date-time)read-only

Timestamp indicating when the SMS received its final status (iso-8601).

Example: "2022-09-30T10:25:00.000Z"
recipientIdsArray of stringsread-only
Example: ["S.20220928-125820.022-0l8likueyRB3CT8FTG"]
Response
application/json
{
  "jobId": "J.20220928-125820.020-0l8likuetGNOTM4A4U",
  "src": "retarus",
  "encoding": "standard",
  "billcode": "Campaign123",
  "statusRequested": true,
  "flash": false,
  "validityMin": 2880,
  "customerRef": "InternalID: ABC1234 Tag: Marketing",
  "qos": "NORMAL",
  "receiptTs": "2022-09-01T10:25:00.000Z",
  "finishedTs": "2022-09-30T10:25:00.000Z",
  "recipientIds": [
    "S.20220928-125820.022-0l8likueyRB3CT8FTG"
  ]
}

SMS Status

Operations

Version

Operations