REST API overview

The client references resources by means of the URL path and the response from API includes JSON links that tie together related resources. The client application needs to use standard HTTP verbs (GET, POST, PUT, DELETE) to access the server API with different methods. The returned HTTP status codes have meaning and must be interpreted by web2SMS client applications.

Each API method is modeled as a resource and has links to operations that are available on the resource depending on the resource state.

2.1 Format of the Response

The web2SMS send SMS message API will use JSON format for encoding the response bodies, setting the appropriate HTTP status codes and content types. The dates are returned in ISO8601 time stamp format (e.g. 2013-12-13T10:57:00+0200).

2.2 Response Status Codes

HTTP response codes are used to indicate:

200 – OK. Used in response to a successful GET Query Status or List Transactions request

201 – Created. Message SMS saved in web2sms platform successful

400 – Bad request; check the error message and correct the request syntax.

401 – Authentication failure, check web2SMS send SMS message API authentication requirements.

403 – Forbidden; provide authentication credentials.

404 – Not found: mistake in the host or path of the service URI.

405 – Method not supported: in web2SMS send SMS message API V1 only POST,GET are supported.

415 – Unsupported media type, when content-type header is not application/json

500 – Error while processing the request

503 – Server busy and service unavailable. Please retry the request. Service in maintenance.

More details on these at

2.3 Handling errors

The general format of the JSON response in case of error is:

HTTP/1.1 400 Bad Request

Content-Type: application/json

Content-Length: 1234

Date: Thu, 04 Jun 2009 02:51:59 GMT

{"error": {

"code": 268435457,

"message": "IDS_App_Controller_Rest_Message__E_AUTH_REQUIRED"


*Parameters: *

error - object contains the error code and message which describes the reason why service cannot accept this request.

code - error code

message - error message

2.4 Authentication

All APIs endpoints will accessible at and accessible only via SSL connection. Each call will be authenticated by web2SMS send SMS message API using BASIC AUTH. ApiKey and secret key shall be communicated by NETOPIA in order for the developer to create the signature.

Basic Auth(apiKey, signature)

Should the authentication failed, the endpoint must return a JSON response with http status code 401 - Unauthorized.

2.5 Resources and URIs

The URIs of the resources implemented by the current API are depicted in the table below:

Resource URI

HTTP Method



Insert a message in web2SMS

Allowed alpha-numeric characters:

ASCII printable characters (character code 32-127)

Codes 32-127 are common for all the different variations of the ASCII table, they are called printable characters, represent letters, digits, punctuation marks, and a few miscellaneous symbols. You will find almost every character on your keyboard. Character 127 represents the command DEL. -

All of these characters will be counted with 1 byte / character

- Exception by making the characters:

form feed, ^ Caret / Circumflex, {Left curly bracket,} Right curly bracket, \ Backslash, [Right square bracket, | Tilde, Right square bracket, | Vertical Bar, € Euro sign (these are counted with 2 bytes, although they are part of the GSM7bit alphabet)

*Careful! If your message contains special characters, they may be displayed incorrectly.

Note that if special characters are sent to the body of the message (where each character is represented by 2 bytes), then the default length of SMS messages will be reduced to 70 (63 characters for concatenated messages).

The special characters are those in the alphabet

The extended ASCII codes (character code 128-255)

There are several different variations of the 8-bit ASCII table. The table below is according to Windows-1252 (CP-1252) which is a superset of ISO 8859-1, also called ISO Latin-1, in terms of printable characters, but differs from the IANA's ISO-8859-1 by using displayable characters rather than control characters in the 128 to 159 range. Characters that differ from ISO-8859-1 is marked by light blue color. -

continue to: 3. API REFERENCE