This guide is designed for software developers who are familiar with the usage of REST-interfaces. If you don’t have any experience in this subject, we recommend the use of our SDKs or the following endpoint: GET /rest/smsmessaging/simple
All endpoints mentioned in this guide can be accessed using the following base URL:
For security reasons, the websms| REST API is limited to HTTPS only, unencrypted connections are not supported.
All requests to the websms| REST API require authentication. The websms| REST API supports basic authentication as well as the usage of an access token (may be created inside the onlinesms web interface).
Sample POST request using Basic Authentication
POST /rest/smsmessaging/text HTTP/1.1
Authorization: Basic dGVzdDp0ZXN0
The Authorization header can be used to send authentication credentials to the server.
The Authorization field (value) is constructed as follows:
- The username and password are combined with a single colon (:)
- The resulting string, e.g. ‘test:test’ is encoded using Base64 (http://de.wikipedia.org/wiki/Base64)
- The Base64 string is then prefixed with the authorization method (Basic) and a space
- The resulting string can then be used as value for the Authorization header.
For more information about HTTP Basic Authentication see http://www.ietf.org/rfc/rfc2617.txt
Sample usage of an access token
Once the access token is obtained (via the onlinesms web interface), it can either be provided as query parameter or as Bearer token within the Authorization HTTP header (see https://tools.ietf.org/html/rfc6750).
Example using the access token as query parameter
GET /rest/smsmessaging/text HTTP/1.1
Authorization: Bearer ACCESS_TOKEN_VALUE
Example using the access token inside the Bearer Authorization header
Requests / Responses
All requests/responens (except
GET /rest/smsmessaging/simple and
POST /rest/smsmessaging/simple) are sent/received as JSON objects. A description of the corresponding request/response objects/parameters is part of each endpoint guide.
The request content type as well as the accepted content type must be defined using the Content-Type and Accept headers:
Basically, the websms| REST API responds with the HTTP Status Code 200 (OK) on every request (both success and error cases).
To provide further information the response includes a statusCode and a statusMessage describing the result of a request.
HTTP/1.1 200 OK
"statusMessage": "message priority is invalid",
Example MessageSendResponse indicating an invalid parameter “priority”