Breadcrumbs

Paths (REST)

Creating a job for sending SMSs 

POST /rest/v1/jobs

Description

This method is used to create and prepare SMS jobs to be transferred for processing. If a valid JobRequest has been received by the Webservice, the Webservice sends an ID back that must be specified by the client when querying the job status.

Parameters

Type

Name

Schema

Body

body
optional

JobRequest

Responses

HTTP code

Description

Schema

200

Successful operation

JobResponse

201

Job successfully created

JobResponse

400

Invalid JobRequest-data (qos, encoding, ..)

No content

401

Authentication failed

No content

409

Duplicate job (detected by enabled duplicate-detection)

No content

422

Invalid JobRequest-data (invalid chars, no messages, ..)

No content

429

Too many requests in the last 10 seconds (retry later)

No content

Consumes

application/json

Produces

application/json

Example - HTTP request

JSON
{
   "options":{
      "src":"retarusREST",
      "encoding":"utf-16",
      "billcode":"Billingcode",
      "statusRequested":true,
      "flash":false,
      "customerRef":"JOBREF.000001",
      "validityMin":5,
      "maxParts":2,
      "invalidCharacters":"TRANSLITERATE",
      "qos":"EXPRESS",
      "jobPeriod":"2018-09-24T11:00:00.000+02:00",
      "duplicateDetection":false,
      "blackoutPeriods":[
         "2018-09-24T12:00:00.000+02:00/2018-09-
24T13:00:00.000+02:00",
         "2018-09-24T18:00:00.000+02:00/2018-09-25T08:00:00.000+02:00"
      ]
   },
   "messages":[
      {
         "text":"Hello Germany...",
         "recipients":[
            {
               "dst":"+4917615500001",
               "customerRef":"RECIREF.001"
            },
            {
               "dst":"+4917500001",
               "customerRef":"RECIREF.002",
               "blackoutPeriods":[
                  "2018-09-24T12:15:00.000+02:00/2018-09-
24T13:00:00.000+02:00",
                  "2018-09-24T20:00:00.000+02:00/2018-09-25T10:00:00.000+02:00"
               ]
            }
         ]
      },
      {
         "text":"Hello USA...",
         "recipients":[
            {
               "dst":"+17615500002",
               "customerRef":"RECIREF.003",
               "blackoutPeriods":[
                  "2018-09-24T19:00:00.000+02:00/2018-09-
24T20:00:00.000+02:00",
                  "2018-09-25T01:00:00.000+02:00/2018-09-25T15:00:00.000+02:00"
               ]
            },
            {
               "dst":"+17500002",
               "customerRef":"RECIREF.004",
               "blackoutPeriods":[
                  "2018-09-24T19:00:00.000+02:00/2018-09-
24T20:00:00.000+02:00",
                  "2018-09-25T01:00:00.000+02:00/2018-09-25T15:00:00.000+02:00"
               ]
            },
            {
               "dst":"+17500003",
               "customerRef":"RECIREF.005",
               "blackoutPeriods":[
                  "2018-09-24T19:00:00.000+02:00/2018-09-
24T20:00:00.000+02:00",
                  "2018-09-25T01:00:00.000+02:00/2018-09-25T15:00:00.000+02:00"
               ]
            }
         ]
      }
   ]
}

Example - HTTP response

Response 200

JSON
{
"jobId" : "J.20180924-131731.737-0iey4kxqyTQCQDIFN1"
}

Response 201

JSON
{
"jobId" : "J.20180924-131731.737-0iey4kxqyTQCQDIFN1"
}

Getting reports for all jobs matching a given criterion 

GET /rest/v1/jobs

Description

This resource delivers a list of Job IDs from a specific time period. Job IDs up to 3 months old can be retrieved.

Type

Name

Description

Schema

Default

Query

fromTs
optional

From timestamp in ISO-8601 format (maximum 30 days before toTs).

string (date-time)


Query

jobIdsOnly
required

Returns only jobIds (must currently always be set to true).

boolean

“true”

Query

limit
optional

Limits the results list to a specific number of Job IDs (0 < limit <=1000).

integer (int64)

100

Query

offset
optional

If the number of results is larger than the limit set for it, with the assistance of the offset, you can query more recent results or skip over a specified number of Job IDs.

integer (int64)

0

Query

open
optional

Restricts the results list to Job IDs that are either still open or have already been completed (blank = both conditions).

boolean


Query

toTs
optional

To timestamp in ISO-8601 format (must be after fromTs).

string (date-time)


Responses

HTTP code

Description

Schema

200

List jobs successful

<JobReport> array

400

Invalid request-parameter

No content

401

Authentication failed

No content

500

Can’t list jobs

No content

Consumes

application/json

Produces

application/json

Example - HTTP response

JSON
[
   {
      "jobId":"J.20180924-131731.737-0iey4kxqyTQCQDIFN1"
   },
   {
      "jobId":"J.20180924-131731.907-0iey4kxqyTFUEFIFN1"
   },
   {
      "jobId":"J.20180924-131731.933-0iey4kxqyTQCOPQRS1"
   }
]

Getting the status for a single job 

GET /rest/v1/jobs/{jobId}

Description

With the assistance of this URL resource, a status report for an SMS job can be requested by Job ID. Status reports can be retrieved for up to 3 months.

Parameters

Type

Name

Description

Schema

Path

jobId
required

The unique job-id

string

Responses

HTTP code

Description

Schema

200

Get job-report successful

JobReport

400

No job-id given

No content

401

Authentication failed

No content

500

Can’t query job-report

No content

Consumes

application/json

Produces

application/json

Example - HTTP response

Response 200

JSON
{
   "jobId":"J.20180924-121731.737-0iey4kxqyTQCQDIFN1",
   "src":"retarusREST",
   "encoding":"standard",
   "billcode":"Billingcode",
   "statusRequested":true,
   "flash":false,
   "validityMin":5,
   "customerRef":"JOBREF.000001",
   "qos":"EXPRESS",
   "receiptTs":"2018-09-24T12:17:44.653+02:00",
   "finishedTs":"2018-09-24T12:19:42.668+02:00",
   "recipientIds":[
      "S.20180924-121800-00001",
      "S.20180924-121800-00002",
      "S.20180924-121800-00003",
      "S.20180924-121800-00004"
   ]
}

Getting information about all recipients of a job 

GET /rest/v1/sms

Description

With the assistance of this resource, a status report for recipients of a job can be requested by Job ID. Status reports can be retrieved for up to 3 months.

Parameters

Type

Name

Description

Schema

Query

jobId
required

The Job ID

string

Responses

HTTP code

Description

Schema

200

List jobs successful get recipients successful

<RecipientReport> array

201

Send job successful

No content

401

Authentication failed

No content

500

Can’t query recipient-report

No content

Consumes

application/json

Produces

application/json

Example HTTP response

Response 200

JSON
[
   {
      "smsId":"S.20180924-114600-00001",
      "dst":"+4917615500001",
      "processStatus":"DONE",
      "status":"SUC_FIN",
      "customerRef":"RECIREF.001",
      "reason":"Delivered to destination.",
      "sentTs":"2018-09-24T18:09:47.445+02:00",
      "finishedTs":"2018-09-24T18:09:52.445+02:00"
   },
   {
      "smsId":"S.20180924-114600-00002",
      "dst":"+4917615500002",
      "processStatus":"OPEN",
      "status":"SUC_ACC",
      "customerRef":"RECIREF.002",
      "reason":"Accepted.",
      "sentTs":"2018-09-24T18:09:47.445+02:00"
   },
   {
      "smsId":"S.20180924-114600-00003",
      "dst":"+4917615500003",
      "processStatus":"OPEN",
      "customerRef":"RECIREF.003"
   }
]

Getting API version information 

GET /rest/v1/version

Description

The Webservice’s version identifier can be queried using this resource.

Responses

HTTP code

Description

Schema

200

Get version-info successful

VersionInfoResponse

Consumes

application/json

Produces

application/json

Example HTTP response

Response 200

JSON
{
   "buildNumber":39,
   "buildTimestamp":"2018-03-26 17:21:55 +0200",
   "majorVersion":2015,
   "minorVersion":10,
   "versionInfo":"REST Interface",
   "message":"1st version."
}