General info

etaAlert is a RESTfull API.
All API URLs are relative to the base URL: http://vapepa.muistutus.fi/api/v1
All API responses have Content-Type:application/json and response body is in JSON format.
With POST and PUT requests, parameters must be submitted in the body as a JSON (while setting Content-Type: application/json).

Authentication

Authentication is handled with authentication token.
Each requests must include a valid authentication token in the X-Authentication-Token header.
All requests must be made over https.

RESTfull

The API uses HTTP verbs and a RESTful endpoint structure as described below:

HTTP Verb	Action	Entire Collection (e.g. /webhooks)	Specific Item (e.g. /webhooks/{ID})
GET	Fetch	200 (OK), list of webhooks.	200 (OK), single webhook. 404 (Not Found), if ID not found or invalid.
PUT	Update	404 (Not Found).	200 (OK). 404 (Not Found), if ID not found or invalid.
POST	Create	201 (Created), Body will contain a JSON of created resource.	404 (Not Found).
DELETE	Remove	404 (Not Found).	204 (No Content). 404 (Not Found), if ID not found or invalid.

HTTP status codes are used to indicate the success or otherwise of requests.

HTTP Code	Description
200 OK	Successful request. Body will contain a JSON hash of response data
201 Created	Successful post request. body will contain a json hash of created resource
204 no content	Successful delete request. body is empty
400 bad request	Error: details in response body
401 unauthorized	Authentication error: response body will contain an explanation
403 forbidden	The request was a valid request, but the server is refusing to respond to it.
404 not found	The endpoint doesn't exist.
500 Internal Server Error	A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
502 Bad Gateway	The server received an invalid response from the upstream server.

Webhook HTTP callback

A Webhook is an HTTP POST request that occurs when a specifc phone number receives a message.
Webhook request is a standard POST request (to customer's defined URL), with JSON data in the request body.

Create a webhook

Webhook event triggering

Data in the webhook body:

Parameter	Description
webhookId	The webhook's unique id.
phoneNumber	The phone number that triggered the webhook.
message	The message that was sent to the phoneNumber.
messageId	The message's unique id.
event	Event name that triggerd the webhook.
sender	Sender's phone number.
timestamp	Timestamp of the event.

Example webhook request

        {
            "webhookId": 1,
            "phoneNumber": "xxxx12342",
            "message": "The message",
            "messageId": 123,
            "messageId": "incoming_sms",
            "sender": "xxxx12344",
            "timestamp": "2015-01-01:00:00:00"
        }

API Errors

Error responses from the API return the http error code in the header and also in the response body. Response body has four common attributes: code, error, type and message, between different error types.

Error examples

Validation error

        {
            "code": 400,
            "message": "Invalid Sms. The Message field is required. The Receiver field is required. The Sender field is required.",
            "error": true,
            "type": "Validation",
            "validationErrors": {
                "message": [
                    "The Message field is required"
                ],
                "receiver": [
                    "The Receiver field is required"
                ],
                "sender": [
                    "The Sender field is required"
                ]
            }
        }

Authentication error

        {
            "code": 401,
            "error": true,
            "type": "Authentication",
            "message":"Your access token is either missing or incorrect. Please check the X-Authentication-Token header and try again."
        }

General server error

        {
            "code": 500,
            "error": true,
            "type": "Server",
            "message":"Internal server error"
        }

Service Unavailable

        {
            "code": 502,
            "error": true,
            "type": "Bad_Gateway",
            "message":"Sms service not reachable"
        }

Endpoints

Smses

POST /smses

Create a new SMS by doinf a POST request with JSON data to the endpoint: https://vapepa.muistutus.fi/api/v1/smses

Headers

Name	Type	Required	Description
X-Authentication-Token	string	Yes	Your authentication token

Parameters

Name	Type	Required	Description
message	string, maxlength 840 characters.	Yes	Content of SMS
receiver	string, international phone number (E.164), +358 country codes only.	Yes	Receiver's phone number
sender	string, international phone number (E.164), +358 country codes only.	Yes	Sender's phone number

Body

{
  'message':'string',
  'receiver':'string',
  'sender':'string'
 }

Headers

Response

HTTP 201 Created

{
  'smsId':'int',
  'message':'string',
  'receiver':'string',
  'sender':'string'
 }

Webhooks

GET /webhooks

Fetch a collection of webhooks by doing a GET request the endpoint: https://vapepa.muistutus.fi/api/v1/webhooks

Headers

Name	Type	Required	Description
X-Authentication-Token	string	Yes	Your authentication token

Parameters

Body

Headers

Response

HTTP 200 OK

[
 {
  'webhookId':'int',
  'phoneNumber':'string',
  'event':'incoming_sms',
  'url':'string'
 },
 {
  'webhookId':'int',
  'phoneNumber':'string',
  'event':'incoming_sms',
  'url':'string'
 }
 ]

GET /webhooks/{webhookId}

Fetch a single webhooks by doing a GET request the endpoint: https://vapepa.muistutus.fi/api/v1/webhooks/{webhookId}

Headers

Name	Type	Required	Description
X-Authentication-Token	string	Yes	Your authentication token

Parameters

Name	Type	Required	Description
webhookId	id	Yes	Id of the the webhook. Used in the URL like: /webhooks/{webhookId}

Body

Headers

Response

{
  'webhookId':'int',
  'phoneNumber':'string',
  'event':'incoming_sms',
  'url':'string'
 }

POST /webhooks

Create a new Webhook by doing a POST request with JSON data to the endpoint: https://vapepa.muistutus.fi/api/v1/webhooks. Webhook is triggered when the phoneNumber receives an SMS.

Headers

Name	Type	Required	Description
X-Authentication-Token	string	Yes	Your authentication token

Parameters

Name	Type	Required	Description
phoneNumber	string, international phone number (E.164), +358 country codes only.	Yes	The phone number which triggers the event.
event	string, incoming_sms only supported.	Yes	The event which the webhook listens.
url	string	Yes	The URL where the webhook should send the POST request when the event occurs.

Body

{
  'phoneNumber':'string',
  'event':'incoming_sms',
  'url':'string'
 }

Headers

Response

HTTP 201 Created

{
  'webhookId':'int',
  'phoneNumber':'string',
  'event':'incoming_sms',
  'url':'string'
 }

PUT /webhooks/{webhookId}

Update a webhook by doing a PUT request with JSON data to the the endpoint: https://vapepa.muistutus.fi/api/v1/webhooks/{webhookId}. Webhook is triggered when the phoneNumber receives an SMS.

Headers

Name	Type	Required	Description
X-Authentication-Token	string	Yes	Your authentication token

Parameters

Name	Type	Required	Description
webhookId	id	Yes	Id of the the webhook. Used in the URL like: /webhooks/1
phoneNumber	string, international phone number (E.164), +358 country codes only.	Yes	The phone number which triggers the event.
event	string, incoming_sms only supported.	Yes	The event which the webhook listens.
url	string	Yes	The URL where the webhook should send the POST request when the event occurs.

Body

{
  'phoneNumber':'string',
  'event':'incoming_sms',
  'url':'string'
 }

Headers

Response

HTTP 200 OK

{
  'phoneNumber':'string',
  'event':'incoming_sms',
  'url':'string'
 }

DELETE /webhooks/{webhookId}

Delete a webhook by doing a DELETE request to the endpoint: https://vapepa.muistutus.fi/api/v1/webhooks/{webhookId}

Headers

Name	Type	Required	Description
X-Authentication-Token	string	Yes	Your authentication to4en

Parameters

Name	Type	Required	Description
webhookId	id	Yes	Id of the the webhook. Used in the URL like: /webhooks/1

Body

Headers

Response

HTTP 204 No Content