Definitions

billcode
required
read-only

Required
Billing code

string

customerRef
required
read-only

Required
Customer reference text (default is null)

string

encoding
required
read-only

Required
Text encoding

string

finishedTs
optional
read-only

Timestamp which indicates when the job received its final status (in accordance with ISO-8601).

Example
"2018-07-09T11:25:24.683+02:00"

string (date-time)

flash
required
read-only

Required
Send as important SMS that automatically appears
on the recipient’s display screen.

boolean

jobId
required
read-only

Required
Job ID

string

qos
required
read-only

Required
Quality of Service. Possible values:

• NORMAL

• EXPRESS

string

receiptTs
required
read-only

Required
Timestamp which indicates when the job was
received by Retarus (in accordance with ISO-8601).

Example
"2018-07-09T11:25:24.683+02:00"

string (date-time)

recipientIds
required
read-only

Required
Ids of the recipients of this job

< string > array

src
required
read-only

Required
Sender ID

string

statusRequested
required
read-only

Required
Delivery notification requested

boolean

validityMin
required
read-only

Required
Validity of the SMS in minutes

integer (int64)

messages
required

SMS messages with different texts and recipients. A minimum of one message must be specified in the list.

Requests which result in more than 3.000 SMS (based on several messages or recipients) will be rejected.

<Message> array

options
optional

Options

jobId
optional
read-only

string

recipients
required

<Recipient> array

text
required

string

billcode
optional

Optional billing information can be entered here.

Max. 70 characters

string

blackoutPeriods
optional

• Specifies time periods during which no SMS are delivered; e.g. if a delivery time is inside such a period, the SMS is scheduled to be sent at the end of the period.

• These periods are based on the ISO 8601 standard.

• Periods that are smaller than 1 hour are expanded to 1 hour (e.g.,: 17:10 - 17:20 is expanded to 17:10 - 18:10)

• If the blackoutPeriods syntax is invalid, the job is rejected
  with a 400 (Bad Request) status code.

• If blackout periods are specified at the Recipient level,
  only they are used. The blackout periods in the Options
  are then ignored.

Examples

• 2018-10-25T18:00Z/2018-10-26T07:00Z

• 2018-10-25T18:00+01:00/2018-10-26T07:00+01:00

< string > array

customerRef
optional

Optional reference information that will be included in getJobReport.

Max. 70 characters (192 for US-ASCII encoding).

string

duplicateDetection
optional

• If enabled, equal requests are rejected with a 409 (Conflict) status code.

• The equality is determined from the REST JSON data.

• Currently, the time window for duplicate detection is 10 minutes. This means that after 10 minutes the same job can be successfully sent once again.

• This parameter should normally be enabled if the customer’s system erroneously generates duplicate requests.

boolean

encoding
optional

The preferred encoding of an SMS. Potential values:

• STANDARD

• UTF-16

When STANDARD is selected, the Webservice checks SMS messages for invalid characters.

The selection of encoding impacts the maximum length of the SMS.

Important information regarding SMS coding using GSM-7 (standard):

• There is a maximum of 160 characters per single-part SMS.

• A maximum of 153 characters per SMS in a multi-part SMS.

• Some special characters, such as, e.g., €, require additional storage capacity (2 normal characters).

SMS encoding with UTF-16

• A maximum of 70 characters when sending a single-part SMS.

• A maximum of 67 characters per SMS in a multi-part SMS.

In some countries, an SMS will not reach the recipient if it
contains special characters.

string

flash
optional

You can set here whether you want the SMS sent as a Flash SMS, which is sent directly to the recipient’s mobile phone display without the recipient explicitly having to open it.

An additional fee is required. The Flash SMS option is not supported in all countries.

boolean

invalidCharacters
optional

Defines how invalid characters in SMS text will be handled.
Possible options are:

• REFUSE: reject job with status-code 422
  (UNPROCESSABLE_ENTITY); see also HTTP-statuscodes
  below.

• REPLACE: replace invalid characters by blank space.

• TO_UTF16: send SMS as UTF-16. Please note: each part now has a maximum of only 70 characters (67 if concatenated).

• TRANSLITERATE: do a smart replacement.

string

jobPeriod
optional

• Timestamp setting the transmission time of the SMS Job. In accordance with the ISO-8601 standard e.g., Z can be +02:00.

• If the jobPeriod syntax is invalid, the job is rejected.

Examples

• 2018-11-01T13:00:00Z

• 2018-11-01T13:00:00+02:00

string (date-time)

maxParts
optional

Sets the maximum amount of SMS in a multi-part (concatenated) SMS. If the SMS message is longer, it is truncated. Permitted values: from 1 to 20. If the specified value is outside of the range of permitted values, either the minimum or maximum value will automatically be selected. The actual length of an SMS is dependent on the selected encoding (see encoding earlier in this section for additional information).

Multi-part SMS are not supported in CDMA
networks.

integer (int32)

qos
optional

Sets the priority of an SMS job. If you have time-critical SMS messages, we recommend that you select the express option. Supported values are:

• normal

• express

An additional fee is required to send an express
SMS.

string

src
optional

The Sender ID displayed to recipient. When entering the Sender ID, note the following technical restrictions:

• If the Sender ID is exclusively numerical, a maximum of 20 numbers can be used. A + character is available for optional use.

• If alphanumeric characters are used, the maximum length is 11. The following characters can be used:
  a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_{|}~

No other characters are permitted.

Java Regular Expressions
(.\\+|)[0-9]{1,20}|[a-zA-Z0-9\\x20\\p{Punct}]{1,11}

p{Punct} stands for the following: !"#$%&'()*+,- ./:;<=>?@[\]^_{|}~.
Pattern: "(\\+|)[0-9]{1,20}|[a-zA-Z0-9\\x20\\p{Punct}]{1,11}"
Example: “retarus”

string

statusRequested
optional

Requests a delivery notification.

An additional fee is required for this option.

boolean

validityMin
optional

Expresses the validity of an SMS in minutes and thus the length of the delivery attempt when an SMS cannot instantly be delivered after being sent (e.g., if the recipient’s mobile phone is shut off).

Supported values are between 5 and 2880 minutes. If the specified value is outside of the range of permitted values, either the minimum or maximum value will automatically be selected.
Exception: 0, in which case the provider’s default value is used.

integer (int64)

blackoutPeriods
optional

• Specifies time periods during which no SMS are delivered (in accordance with ISO-8601). E.g. if a delivery time is inside such a period, the SMS is scheduled to the end of the period.

• These periods are based on the ISO 8601 standard.

• Periods that are smaller than 1 hour are expanded to 1
  hour (e.g.,: 17:10 - 17:20 is expanded to 17:10 - 18:10).

• If the blackoutPeriods syntax is invalid, the job is rejected
  with a 400 (Bad Request) status code.

• If blackout periods are specified at the Recipient level,
  only they are used. The blackout periods in the Options
  are then ignored.

< string > array

customerRef
optional

Discretionary reference information. If no value is specified, the recipient mobile phone number specified in the dst field will be applied. This information is included in the status report.

Max. 70 characters.

string

dst
required

Recipient’s mobile phone number. If a number is specified without a country code, the value specified in the Country code parameter will automatically be applied.

string

customerRef
optional
read-only

Discretionary reference information. Set during transmission. This information is included in the status report.

Max. 64 characters.

string

dst
optional
read-only

Recipient’s mobile phone number. Set during transmission.

string

finishedTs
optional
read-only

Timestamp which indicates when the SMS received its final status (in accordance with ISO-8601).

Example
"2018-07-09T11:25:24.683+02:00"

string (date-time)

processStatus
optional
read-only

Current status of the process (see SMS outbound status codes - REST).

string

reason
optional
read-only

Explanation of the status.

string

sentTs
optional
read-only

Timestamp which indicates when the SMS was sent (in accordance with ISO-8601).

Example
"2018-07-09T11:25:24.683+02:00"

string (date-time)

smsId
optional
read-only

Recipient ID

string

status
optional
read-only

Status (see SMS outbound status codes - REST).

string

buildNumber
optional
read-only

Revision number.
Example - 39

integer (int32)

buildTimestamp
optional
read-only

Date created.
Example - "2018-03-26 17:21:55 +0200"

string

majorVersion
optional
read-only

First component of the version number.
Example - 2015

integer (int32)

message
optional
read-only

Additional information about the current version.

string

minorVersion
optional
read-only

Second component of the version number.
Example - 6

integer (int32)

versionInfo
optional
read-only

Additional information about the REST interface.

string