Paths (REST)

Creating a job for sending SMSs

TEXT

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
500	Can’t accept job or unable to transliterate sms-text	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

TEXT

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

TEXT

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

CODE

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

TEXT

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."
}