ElementarySMS RestAPI version 1.05

Welcome to ElementarySMS RestAPI Documentation

Last update: 2016.01.12

The ElementarySMS API is built on HTTP, is RESTful and it:

• Uses predictable, resource-oriented URLs.
• Uses built-in HTTP capabilities for passing parameters and authentication.
• Responds with standard HTTP response codes to indicate errors.
• Returns JSON.

Base URL

All API URLs referenced in this documentation start with the following base part:

http://elementarysms.example.com/api

You'll have to replace http://elementarysms.example.com with the URL of your ElementarySMS Web Application installation.

Input and Output Formats

Unless otherwise specified, all API calls will require and return a JSON-formatted payload.

Authenticating API Requests

Authentication to ElementarySMS API occurs via Basic Access Authentication as described in RFC2617.

• The user name is always api-user.
• The password is the API Key found in System Settings -> API Section of your ElementarySMS Web Application installation.

Here is how to use Basic Access Authentication with curl:

curl --user api-user:XXSSDDESSQQ

Sending Data to the APIs

By default, all API calls expect a JSON-formatted payload.

Here is a sample curl call for /message/add:

curl --user api-user:XXSSDDESSQQ -H "Content-Type: application/json" -X POST \
-d '{
     "number": "+40722001002",
     "message": "This is a message sent through ElementarySMS API.\nHave a nice day :)"
    }' \
http://elementarysms.example.com/api/message/add

Special note about handling new lines

If you want to use a new line in your message body, replace the new line with \n.

Receiving Data from the APIs

By default, all API calls will return a JSON-formatted payload.

Here is a sample response from /message/add call:

{
  "status": "success",
  "uuid": "ea4b0fee-72ab-4d1f-9087-e8683ba355cf"
}

Date and Time Format

JSON does not have a built-in date type. Dates are passed or retrieved as Unix Time.

Here is a sample response from /message/status call:

{
  "status": "success",
  "e6a0ed30-5c48-11e5-b604-2a042924705f": {
      "device": "359385052343557",
      "status": "delivered",
      "added_at": 1442390388,
      "queued_at": 1442390418,
      "sent_at": 1442390419,
      "delivered_at": 1442390437,
      "sms_count": "1"
   }
}

Using a specific Device

If you want to use a specific Device for an API call, you can pass a device_id parameter. You can find the Device ID in Devices section of your ElementarySMS Web Application installation.

Here is a sample payload for /message/add call using a specific device_id:

{
  "number": "+40722001002",
  "message": "Hello John Doe, welcome to our site !",
  "device_id": "LS1437838000"
}

Common HTTP Error Codes and Error Messages

HTTP status code 400

{
  "status": "error",
  "message": "Invalid JSON data !"
}

HTTP status code 401

{
  "status": "error",
  "message": "Invalid credentials !"
}

API References