SMS API REST Web Service

The json body of the request can contain maximum 500000 UTF-8 encoded characters.

A successful request will return 200 OK and a json document of either of the two following formats (depending on the shownumberparts/N parameter). Note that the request for sending is successful even if the send status of some SMS sendings are failed. A successfully sent message may sometimes not be delivered due to external factors (phone turned off, phone subscription expired, no such subscriber), but such requests will be reported as successful by this endpoint, and the later fortune of the message can be followed via the /status or /status/single endpoints. A scheduled message is reported as accepted, and will have status SCHEDULED until the scheduled send time. The Content-Type header of the response is application/json for all responses.

Or with number of parts enabled

Note that in this example, the mobile recipient number was accepted while the alphanumeric recipient number was rejected. Note that the checknumber parameter will lead to rejection of some unofficial mobile numbers, e.g. the extra long numbers issued as a group of numbers by some operators as a less expensive way of having many different numbers. These are usually not real mobile phones, but may in some cases be Internet-of-things-type devices, so to send to such numbers, checknumber should be set to false.

will output

A user, or a company with many users, can have an address book in the service, with contacts that each contain a phone number that can receive SMS messages. These contacts can be marked with tags consisting of a tag type and a tag value. For instance, a contact can be marked with the tag Base:STO if the person is based in Stockholm. The same contact can have many tags, for instance Group:Management or On call:Yes. Which tags types and tag values are used is up to the user/company, but they should preferably consist of letters and numbers, and can especially not contain the characters ;, | or :. A tag filter in the SMS rest interface consists of a list of filter parts, which are connected by logical AND (a contact is selected only if it fulfills every part of the filter). A filter part consists of a tag type and a list of tag values. A contact fulfills the filter part criterion if it has a tag with the given tag type and one of the given tag values (logical OR). Filters can be given either as a string in GET or POST or as a json document in the POST input. Using the string notation, the example contact would fulfill a Base:STO|OSL|CPH;On call:Yes filter, which consists of two filter parts, one saying that the contact needs to have a Base:STO or a Base:OSL or a Base:CPH tag, and the other that the contact needs to have an On call:Yes tag. Note that filter parts are separated by a semicolon, tag type and tag values are separated by a colon and tag values are separated by vertical bars (UNIX pipe symbols).

A user may have access to several address books, but only the address book set as default address book for the user will be searched with the tag filter.

If a tag filter is given, the to parameter is optional, and any numbers selected both by the filter and by the to parameter will not receive duplicate messages but only one. Only one tag filter can be given per send call.

In the following three parameter examples (two POST, one GET), the same tag filter is specified. Note the URL-encoding of the filter string in the GET parameter.

Tag filters may be saved in the address book for repeated use, under a name. Note the toaddressbooksavedtagfilters/S parameter which takes a list of such names.

It is recommended to use the more flexible tag filters, but legacy customers using named groups/distribution lists can give a list of such names in the toaddressbookgroups/G parameter.

It is sometimes convenient to use a set of standard message templates where only a part of the message text is unique to the individual message. In such a template, some character sequences function as place holders, which are to be substituted with the individualized text pieces. In the web portal, such templates can be edited and stored with an id. The id of the template is shown on the editing page in the newest version of the web portal, and is used in this API with the templateid / TPID parameter. If a template id is given, any explicit message given in the message / M / M8 parameters is ignored. When no template id is given, a template text with placeholders for substitutions can be equally well be supplied as the message.

Currently, this API allows substitutions in messages to recipient phone numbers that are explicitly entered, with substitution texts that are also explicitly entered (i.e. not for search results from tag filters and not substituting with stored data e.g. from address book contact entries).

The POST version of the /send endpoint uses the tosubst field to specify the substitutions to be used for each number. The field is a json list of objects, where each object has a to field and a subst field. The to field is a string with the recipient number, and the subst field is a json object, with the form of what is called a dictionary, library, or map of string to string in different programming languages, where the place holders are keys and the texts to substitute are the corresponding values.

The GET version of the /send endpoint uses the TS and H parameters for the same purpose as the tosubst field in the POST version. The H parameter is a list of k place holders, and the TS parameter has k+1 comma separated (url encoded utf-8) strings per recipient, where the first is the recipient number and the next k are the substitutions.

In the /send/single endpoint, where all efforts are aimed at a simple, flat input object, the phone number is given in the same to field as non-substituted messages, and the holderX and substX fields are used to specify place holder substitutions. This endpoint sends to one recipient per call.

In the newest version of the web portal, the feature for editing and saving text templates is improved to allow a use case where logged-in users send single SMS messages by manually adding individual data for slots in the template message into input boxes on the SMS sending web page, allowing a coherent messaging strategy between different recipients. When editing such a template in the web portal, convenient buttons add place holders of the form {Text:customer} or {Text:ITEMNO} or {Text:City:Location of the store} or {DateTime:today}. In this API, there is a short-cut to substitute such template derived place holders in in the same way as place holders without curly brackets, taking care to keep the upper-case and lower-case exactly as in the template. Any curly bracket substitutions not given a value are replaced with the empty string in the output message. Substitutions not found in the template are ignored. Note that the editing page can also add place holders for data pertaining to the logged-in user or the address book contact of the recipient, and these types are not supported currently in this API.

If any labels used inside the curly bracket place holders happen to coincide exactly with words in the message, there is a parameter onlytemplateplaceholders / TPONLY that can be used to not substitute the single words but only the place holders from the saved template.

Will become "Hello Anna! You are our best Anna." with onlytemplateplaceholders=false, and "Hello Anna! You are our best customer." with with onlytemplateplaceholders=true

The /send/single endpoint accepts a single string field as the "to" parameter, and does not accept any parameters that may lead to sending messages to more than one recipient (groups, tag filters etc.)

The json body of the request can contain maximum 10000 UTF-8 encoded characters.

A successful request will return 200 OK and a json document of the following format. A failure to attempt sending due e.g. to an invalid recipient phone number will return an appropriate error code, e.g. 400 Invalid request. A successfully sent message may sometimes not be delivered due to external factors (phone turned off, phone subscription expired, no such subscriber), but such requests will be reported as successful by this endpoint, and the later fortune of the message can be followed via the /status or /status/single endpoints. A scheduled message is reported as accepted, and will have status SCHEDULED until the scheduled send time. The Content-Type header of the response is application/json for all responses.

A POST call with default parameters, where the authorization credentials are supplied via Basic Authentication or X-Lekab-headers can supply either a zero-length body or an empty JSON document with the same result.

A successful request will return 200 OK and a json document of the following format. The Content-Type header of the response is application/json for all responses.

Note that in this example, three of the listed statuses were found, while two were not. If the user is not allowed to read a status for a certain id, because that message belongs to another user, this is treated as not found.

The following message status codes can be received in the message status.

A later status update from the mobile carrier is quite likely to change the value.

QUEUED (0), SENT (1), SCHEDULED (14)

When the status is updated, the read flag is cleared to unread status, and the new status will be retrieved the next time reading. Note that when the recipient’s phone is turned off, this is where the status is stuck until the phone is turned on or the message expires.

The recipient’s phone has supposedly acknowledged receipt of this message.

DELIVERED (2)

The recipient will not get this message.

DELETED (3), EXPIRED (4), REJECTED (5), UNDELIVERABLE (6), ABSENTSUBSCRIBER (8), UNKNOWNSUBSCRIBER (9), INVALIDDESTINATION (10), SUBSCRIBERERROR (11), ERROR (13), CANCELED (15)

Probably failing final statuses (probably the mobile carrier has lost or dumped the message, but it may suddenly turn up).

ACCEPTED (7), UNKNOWN (12)

will output

The /status/single endpoint accepts a single string field as the "id" parameter, and if no id is given a maximum of one (1) unread status change is returned.

A POST call with default parameters, where the authorization credentials are supplied via Basic Authentication or X-Lekab-headers can supply either a zero-length body or an empty JSON document with the same result.

A successful request will return 200 OK and a json document of the following format. The Content-Type header of the response is application/json for all responses.

If the id given does not correspond to a sent SMS that the requesting user is allowed to see, or if no id is given and no unread status change is available, a 404 Not found error will be returned.

The status values are described above, in the explanations of the /status endpoint.

A POST call with default parameters, where the authorization credentials are supplied via Basic Authentication or X-Lekab-headers can supply either a zero-length body or an empty JSON document with the same result.

A successful request will return 200 OK and a json document of the following format. The Content-Type header of the response is application/json for all responses.

Note that in this example where no ids are requested, the list of not found ids will always be empty.

Example code for /incoming will be very similar to that for /status above

The /incoming/single endpoint accepts a single string field as the "id" parameter, and if no id is given a maximum of one (1) unread incoming SMS is returned.

A POST call with default parameters, where the authorization credentials are supplied via Basic Authentication or X-Lekab-headers can supply either a zero-length body or an empty JSON document with the same result.

A successful request (at least incoming SMS was retrieved) will return 200 OK and a json document of the following format. The Content-Type header of the response is application/json for all responses.

If the id given does not correspond to an incoming SMS that the requesting user is allowed to see, or if no id is given and no unread incoming SMS is available, a 404 Not found error will be returned.