Alarms :

All the examples in this Section will use Bearer Authentication (using JWT Tokens). Please read our Authentication Section to know how to retrieve & use your JWT token.

An alarm is a warning noti fication that something interesting/unexpected has happened. When an alarm is triggered, it will displayed on Situm' Dashboard Real Time Panel and it will also be available in through this API. Alarms are mostly triggered by Situm MRM application, but can also be created using this API. Currently, Situm allows a reduced set of alarm types:

DANGER. Indicates that somebody is in danger. Situm MRM triggers this alarm when the user hits the "Alarm Button" or taps the phone repeatedly.
DEADMAN. Indicates that somebody has fallen down. Situm MRM triggers this alarm when the user falls down and lays on the ground for some time.
BREACH. (Do not use!) Indicates that an user of Situm MRM app has missed a step of a round.
EMERGENCY. (Do not use! Deprecated!) Indicates that an emergency has been triggered.
STATIONARY. (Do not use!) Indicates that an user of Situm MRM app has been idle for a long time.

Alarms can go through a series of states:

OPEN. When an alarm is created, this is always the first state. It means that the alarm has not been attended yet. An OPEN alarm can not be re-openned.
CLOSED. This is the state that the alarm will be assigned when it has been attended. A CLOSED alarm can not be re-openned.
CONFIRMED (DO NOT USE). Indicates that the alarm has been confirmed (e.g. it is not a false alarm).
MARKED_FALSE (DO NOT USE). Indicates that the alarm has been confirmed as a false alarm.
OTHER (DO NOT USE). Other unknown state.

Creating Alarms

To create an alarm, you may use a Curl like the following one:

curl --location --request POST 'https://dashboard.situm.com/api/v1/alarms' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer MYJWTTOKEN' \
--data-raw '{
    "type": "DANGER",  //Alarm type
    "building_id": 8359, //Building identifier where the alarm will be issued
    "x": 1, //X-cartesian geolocation of the alarm
    "y": 1, //Y-cartesian geolocation of the alarm
    "lat": 40.2820881, //Latitude of the alarm
    "lng": -4.7498971, //Longitude of the alarm
    "floor_id": 20485, //Floor identifier where the alarm will be issued
    "created_by": "587344a2-fbe4-4970-b7b3-8fd0baa75366" //UUID of the user who issues the alarm
}'

If you don't know the user identifier (UUID), you may use the GET Users endpoint to retrieve all the users of your account. For example:

curl --location --request GET 'https://dashboard.situm.com/api/v1/users' \
--header 'Authorization: Bearer MYJWTTOKEN'

The user UUID will be the "id" parameter:

    "data": [
        {
            "admin": false,
            "id": "6a9f6201-c630-44a4-9e8f-64fc9f3fac6e",
             ....
       }
    ]
   ...

If you go to Situm Dashboard's Real Time panel, you should see something like this:

Other parameters

You may also add the following parameters to your request:

{
   ...
    "message": "Any message associated to the alarm (e.g. Found suspicious bag)",
    "action": "Description of the action to be taken (e.g. Send team)",
    "location_description": "Description of the alarm geolocation (e.g. Main Lobby)",
    "custom_fields": [
        {
            "key": "key1", 
            "value": "value1"
        }
    ]

}

Retrieving alarms

You may retrieve all the alarmseate an alarm, you may use the following command. The building_id query param is mandatory (8359 in this example):

curl --location --request GET 'https://dashboard.situm.com/api/v1/alarms?building_id=8359' \
--header 'Authorization: Bearer MYJWTTOKEN'

The response will look like this:

{
        "uuid": "ef804d7d-6f5e-47b2-b88c-fc6cc6cd2abf", //Alarm UUID
        "x": 1.0,  //X-cartesian geolocation
        "y": 1.0, //Y-cartesian geolocation
        "lat": 40.2820881, //Latitude
        "lng": -4.7498971, //Longitude
        "outside": true, //Legacy data -> Don't use
        "inside": true, //Legacy data -> Don't use
        "created_at": "2021-03-30T09:04:45.804+0000", //Creation timestamp
        "updated_at": "2021-03-30T09:04:45.804+0000", //Last update timestamp
        "created_by": "587344a2-fbe4-4970-b7b3-8fd0baa75366", //UUID of the user who created the alarm
        "floor_id": 20485, //Floor Identifier of alarm geolocation
        "building_id": 8359, //Building identifier of alarm geolocation
        "type": "DANGER", //Alarm type
        "status_changes": [  //See Status Changes for details
            {
                "status": "OPEN",
                "message": null,
                "action": null,
                "uuid": "9447c103-4d0b-4ffb-a3cc-d7476fcc80c7",
                "user_uuid": null,
                "created_at": "2021-03-30T09:04:45.817+0000",
                "location_description": null
            }
        ],
        "chat_room": null, //Legacy data --> Don't use
        "active": true, //Whether alarms is active or not. This is redundant with the state -> Please use current_state parameter
        "current_state": "OPEN" //Current state
    }

You may also retrieve the information of an specific alarm (ef804d7d-6f5e-47b2-b88c-fc6cc6cd2abf in this example) with a similar result, for instance:

curl --location --request GET 'https://dashboard.situm.com/api/v1/alarms/ef804d7d-6f5e-47b2-b88c-fc6cc6cd2abf' \
--header 'Authorization: Bearer MYJWTTOKEN'

Closing alarms

To close an alarm, you should create an "Status Change" from OPEN to CLOSED state. For example, to close alarm "a381cd7b-573a-45d8-bae7-8b14fb7bce51" you should do as follows:

curl --location --request POST 'https://dashboard.situm.com/api/v1/alarms/a381cd7b-573a-45d8-bae7-8b14fb7bce51/status_changes' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer MYJWTTOKEN' \
--data-raw '{
    "user_uuid": "587344a2-fbe4-4970-b7b3-8fd0baa75366", //UUID of the user who creates the Status Change
    "status": "CLOSED" //New status

}'

The result will show the history of alarm status, where the last one will be "CLOSED":

{
    "uuid": "a381cd7b-573a-45d8-bae7-8b14fb7bce51",
    ....
    "status_changes": [
        {
            "status": "OPEN",
            "message": null,
            "action": null,
            "uuid": "093b0a66-2344-4533-9fea-2b742be4658e",
            "user_uuid": "587344a2-fbe4-4970-b7b3-8fd0baa75366",
            "created_at": "2021-03-30T09:22:58.893+0000",
            "location_description": null
        },
        {
            "status": "CLOSED",
            "message": null,
            "action": null,
            "uuid": "ff73dc83-aba7-4522-bbe5-66c760f955f6",
            "user_uuid": "587344a2-fbe4-4970-b7b3-8fd0baa75366",
            "created_at": "2021-03-30T09:38:00.291+0000",
            "location_description": null
        }
    ],
   ....
    "active": false,
    "current_state": "CLOSED"
}

Deleting alarms

You may also delete an alarm to erase all its information from Situm Platform. For instance, if we want to delete alarm ef804d7d-6f5e-47b2-b88c-fc6cc6cd2abf, we would just issue the following command:

curl --location --request DELETE 'https://dashboard.situm.com/api/v1/alarms/ef804d7d-6f5e-47b2-b88c-fc6cc6cd2abf' \
--header 'Authorization: Bearer MYJWTTOKEN'

Alarms Print

Related Articles