# Send alarms using REST

To send an alarm via a REST API method, you need to submit the following request:

## create a simple alarm via the API

<mark style="color:green;">`POST`</mark> `https://talos.evalink.io/api/alarm-service/alarms`

Use this endpoint to send an alarm in evalink talos for a specific site (device) and company.\
\
**NOTE: The endpoint might respond with HTTP 406 Not Acceptable - this should be treated as success.**\
HTTP 406 means that talos is configured to not accept this particular alarm, but the transmission itself was successful.\
\
**NOTE: The endpoint might respond with HTTP 400 Bad Request - you should not retry the transmission.**\
When the endpoint returns HTTP 400 it means that something is wrong with your request, in this case the client should declare a failure and not retry transmission of the alarm as any subsequent transmission will also fail.

#### Headers

| Name          | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| Authorization | string | Use 'Bearer' followed by your API token. |

#### Request Body

| Name            | Type    | Description                                                                                                                                                                                                                                                                       |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| evalinkDeviceId | string  | Alternatively to providing the `deviceId` field you can provide the evalinkDeviceId to identify the Site. (max 30 characters).                                                                                                                                                    |
| timestamp       | number  | Time of alarm occurrence in milliseconds                                                                                                                                                                                                                                          |
| source          | string  | Name of the system where the alarm originated from (e.g. virtual-vds-receiver, talos-ui)                                                                                                                                                                                          |
| alarmMsg        | string  | Optional message to show alongside the alarm code, if not provided the message is chosen from the alarm definition                                                                                                                                                                |
| alarmDefinition | string  | The name of an existing alarm definition in the talos company - if not provided the proper alarm definition is selected automatically                                                                                                                                             |
| testMessage     | boolean | Optional flag to mark an alarm as testMessage                                                                                                                                                                                                                                     |
| alarmValue      | boolean | The alarmValue of the alarm, true = alarm, false = restore. For SIA this field isn't required because the alarm values are defined in the talos alarm definitions.                                                                                                                |
| headers         | string  | A list of key/value pairs to add arbitrary information to the alarm like video verification, geolocation, messages etc.                                                                                                                                                           |
| partitionName   | string  | The readable name of the partition where the alarm occurred                                                                                                                                                                                                                       |
| partition       | string  | The partition id where the alarm occurred (also known as "area")                                                                                                                                                                                                                  |
| alarmZoneName   | string  | The readable name of the zone where the alarm occurred                                                                                                                                                                                                                            |
| alarmZone       | string  | The zone id where the alarm occurred                                                                                                                                                                                                                                              |
| companyId       | string  | The Company ID, as it is displayed on the evalink talos Web Interface. (At the API Token page) - 36 characters.                                                                                                                                                                   |
| deviceId        | string  | <p>The Device ID, as it is displayed in the evalink talos interface. (In the URL when looking at a Site) - 32 characters.<br><em>Alternatively you can also provide the <code>evalinkDeviceId</code> field and talos will internally resolve it to the correct deviceId.</em></p> |
| alarmCode       | string  | The relevant alarm code, e.g. 100, 101, FA etc. - can be any string, but its best to follow a defined alarming standard.                                                                                                                                                          |

{% tabs %}
{% tab title="200 " %}

```
{
    "id": "5e85a1a278fd457b997dc35a54058XXX",
    "shortId": "7534-6539",
    "headers": [
        {
            "name": "x-tags",
            "value": "centralsite;headquarters"
        }
    ],
    "companyId": "bc2b4013-664a-46ab-a1be-a85c31a6xxxx",
    "deviceId": "8a81b69d749bc70f0174b0db7b9dxxxx",
    "deviceGroupId": "8a81cfd075080abb01752c2db145XXXX",
    "alarmStatus": "IN_WORK",
    "timestamp": 1607598290721,
    "alarmStoredTimestamp": 1607598290721,
    "source": null,
    "testMessage": false,
    "messageId": null,
    "payload": null,
    "alarmValue": true,
    "alarmCode": "BA",
    "alarmMsg": null,
    "alarmZone": null,
    "alarmZoneName": null,
    "partition": null,
    "partitionName": null,
    "technical": false,
    "alarmType": "BURGLARY",
    "severity": 6,
    "definition": "sit:SIA",
    "channelId": null
}
```

{% endtab %}
{% endtabs %}

Example Request:

```
{
  "companyId": "<companyId>",
  "deviceId": "<deviceId>",
  "alarmCode": "BA",
  "alarmValue": true,
  "timestamp": 1629981339172,
  "alarmZone": "1",
  "alarmZoneName": "Garage",
  "partition": "5",
  "partitionName": "Office Building",
  "source": "virtual-dc09-receiver",
  "headers": [
    {
      "name": "latitude",
      "value": "38.8951"
    },
    {
      "name": "longitude",
      "value": "-77.0364"
    },
    {
      "name": "message",
      "value": "Some message that is shown in the alarm list"
    },
    {
      "name": "attachment.url",
      "value": "https://some-url-to-show-the-operator"
    },
    {
      "name": "attachment.image",
      "value": "https://url-to-some-image"
    },
    {
      "name": "attachment.widget",
      "value": "src=https://url-to-a-widget-website;height=300px"
    },
    {
      "name": "attachment.talos.video",
      "value": "/api/storage-service/uploads/{file-id}"
    },
    {
      "name": "attachment.talos.image",
      "value": "/api/storage-service/uploads/{file-id}"
    },
    {
      "name": "attachment.talos.file",
      "value": "/api/storage-service/uploads/{file-id}"
    }
  ]
}
```