--- title: API Documentation slug: alarm-filter/api-documentation docTags: createdAt: 2024-02-07T15:29:02.013Z --- Irisity Alarm Filter supports SMTP and HTTPS as the main ways of connecting to the system. We also offer custom integrations and vendor-specific handling of certain alarms. Please follow our [Getting started](docId\:cY5W0lccHHV9ZJwuw4zda) to prepare the system and set up API keys and SMTP credentials. # Use HTTPS when possible When possible, configure the alarms to be sent using HTTPS. Input the following HTTP details: ### HTTPS endpoint settings   **URL:** https\://in.alarmfilter.irisity.io   **Port:** 443   **API-KEY**: \ ### HTTPS camera identification When making the request, add query parameters to identify the camera. An example of this could be `POST https://in.alarmfilter.irisity.io/?c=unique-camera-id-123` ### HTTPS - Send images or the clip in the body Encode the body of the request as [multipart/form-data](https://datatracker.ietf.org/doc/html/rfc2388) and send the images or clip. :::hint{type="info"} ### Camera identification for HTTPS When we parse incoming HTTPS alarms we try to identify the camera based on the incoming request. ::: # SMTP/email is also supported If HTTPS is not supported or you prefer to use SMTP, use the following configuration for the ### SMTP server settings   **Email Server (SMTP):** s.alarmfilter.irisity.io   **Username**: \   **Password:** \   **Port:** 587   **Encryption:** TLS ### SMTP recipient settings   **To:** unique-camera-id-123456\@alarmfilter.irisity.io   **From:** \ # Incoming email alarm parsing Each alarm sent to the alarm filter must contain either a short video clip (preferred) or multiple image frames that jointly make up a video sequence from a surveillance camera. This video or image sequence will be called video, video clip, and clip, interchangeably. The video or separate images should be at least three frames long, preferably 6-10 frames. At least three images/frames are required for the filter to detect motion in the video. Based on the video clip, each incoming alarm video will be classified as either a True alarm or a False alarm. For SMTP, the video or images are sent as attachments to the email. For HTTPS, the video or images are sent through the body of the HTTP request. ## True alarms True alarms are alarms that **contain human activity**, meaning people or vehicles moving. ## False alarms False alarms are other alarms. ## Filtering performance You can expect the Irisity Alarm Filter to filter out more than 95% of all incoming False alarms while removing very few True alarms. # APIs The incoming email service will parse incoming emails using one of multiple *API providers*. If no specific API is specific, the *Generic *provider will be used. Currently, these providers exist for SMTP: - Generic - Hikvision-1 The following providers exist for HTTPS: - Generic The details of each API will be detailed in the following sections. ## Camera incoming ID The main goal of the parsing is to **tie each incoming alarm to a unique i*****ncoming ID***. Each camera needs to have a unique i*ncoming ID*. Depending on the *API *used and the parameters sent, this unique name will be either assigned (most common) or explicitly set. The incoming id will *always* be calculated for each incoming alarm, and we recommend where possible to set it explicitly. Examples of setting the incoming camera id explicitly: - (SMTP) To: `camera-864020@af.irisity.io` or equivalently `id=camera-864020@alarmfilter.irisity.io` or `camera-id=camera-864020@alarmfilter.irisity.io` - (HTTPS) `https://in.alarmfilter.irisity.io?id=camera-86402` or equivalently `https://in.alarmfilter.irisity.io?incoming-id=camera-86402` ## Parsing - it starts with the recipient (to) address The main method of parsing emails starts with the recipient (to) address of the email. This is because most surveillance cameras and network equipment have very limited support for user-definable data and parameters anywhere else. Depending on the *API *used special parsing may be done that uses other fields, such as the email body or attachments. The main method of parsing HTTP requests is done by passing in query parameters in the HTTP query request. In the documentation below square bracket `[...]` will be used to show template variables and user-definable input. `[camera-incoming-id]` means that the unique ID of that camera is expected, an example provided by a user could be `camera-841748`. Note that the square brackets should be omitted when transforming the templates to the real world. Specific API parameters are given in the `[key]=[value]` format. Keys are always transformed to lowercase, meaning casing typically does not matter. ### Note for IMMIX users The simplest way to set up cameras for easy integration with IMMIX is to make the incoming camera ID match IMMIX's IDs. IMMIX supports three different identifiers: - Server ID ("S number", originating device identifier) - S1234 Typically used to correlate a group of cameras to a Site in IMMIX - Alarm Input ID ("A number", alarm input number) - A123 Typically used to specify alarm details, alarm type, etc. The most typical example would be to specify S-number and A-number. Some examples using the SMTP API: - TO: `S1234-A12@alarmfilter.irisity.io` or equivalently `id=S1234-A12@alarmfilter.irisity.io` or: `incoming-id=S1234-A12@alarmfilter.irisity.io` Would send 1234 as the S number and 12 as the A number to Immix. In the Alarm Filter system, the `incoming camera id`parameter would be `S1234-A12` and the camera name would be `S1234 A12`. - TO: `S1234@alarmfilter.irisity.io` Would send 1234 as the S number. The camera would be named `S1234` - TO: `S1234-A12&folder=My-site-1@alarmfilter.irisity.io` Would send 1234 as the S number and 12 as the A number to Immix. In the Alarm Filter system, the `incoming camera id`parameter would be `S1234-A12` and the camera would be placed in a folder called `My site 1` - TO: `folder=My-site-1&camera=Camera-1-North-gate&incoming-id=S1234-A12@alarmfilter.irisity.io` or shortened `f=My-site-1&c=Camera-1-North-gate&id=S1234-A12@af.irisity.io` - All parameters are specified explicitly by name. - Would send 1234 as the S number and 12 as the A number to Immix. - In the Alarm Filter system, the `incoming camera id`parameter would be `S1234-A12` - The camera would be in a folder called `My site 1` - The user-facing name of the camera would be `Camera 1 North gate` ## Allowed length, characters, and query string parameters Email addresses are limited in the characters they support. Our parsing is based on a subset of [URL query strings](https://en.wikipedia.org/wiki/Query_string). Supported characters are: - Letters (`A–Z` and `a–z`), numbers (`0–9`), and the character `-` (hyphen). - When `-` (hyphen) is used it will be transformed to (space) when generating user-facing names. - While special character encoding is technically supported, we do not recommend using it. Character encoding is done using the `%HH` hexadecimal representation of that character. Formally, email addresses are bound by the [RFC5322](https://datatracker.ietf.org/doc/html/rfc5322) standard ([Wikipedia](https://en.wikipedia.org/wiki/Email_address)), which supports query strings. However, many devices have additional constraints, see below. ## Restrictions for SMTP: ### Max length 64+63 characters (or just 64 in total) The RFC standard specifies - Max 64 characters for the User part of an email (before the @) - Max 63 characters for the Domain part of an email (after the @) where an email address is \[User]@\[Domain]. There are, however, devices that set the **total limit to 64 characters**. ### Lacking support in many cameras and NVRs! Due to lacking support in many cameras and other network equipment, we provide a fallback: - `&` can be replaced by `.` in all examples below (ampersand replaced by a dot). - `=` can be replaced by `_` in all examples below (equals replaced by underscore). This means that the following two email recipient addresses are equivalent and will be parsed the same way: `folder=folder-1&camera=camera-1@alarmfilter.irisity.io` `folder_folder-1.camera_camera-1@alarmfilter.irisity.io` ### Shortening the email address The length limit can sometimes be a problem. We therefore support shorthands: - `...@alarmfilter.irisity.io` can be replaced by `...@af.irisity.io` - Each parameter listed below has a shorthand: - `api=` can be replaced with `a=` - `camera=` can be replaced with `c=` - `folder=` can be replaced with `f=` - `nvr=` can be replaced with `n=` ## Recipient field format The recipient field takes one of two main formats - `[incoming-camera-id]@alarmfilter.irisity.io` This method is used when the unique incoming ID is known - `[param1]=[value1]&[param2]=[value2]&[param3]=[value3]...@alarmfilter.irisity.io` ## Selecting the right API To select the right api, the `api=[the-selected-api]` parameter is used. The shorthand for `api=` is `a=`. Four examples are given below - **SMTP**: `camera-841748@alarmfilter.irisity.io` **HTTPS**: `https://in.alarmfilter.irisity.io?camera=camera-841748` No `api` parameter is given, meaning the `Generic` API is selected - **SMTP**:`api=hikvision-1&[other-parameters]@alarmfilter.irisity.io` The `hikvision-1` api is selected - **SMTP**:`a=hikvision-1&[other-parameters]@af.irisity.io` An equivalent shorthand version of the above - `api=unknown-api` In cases where the selected API is unknown, the email will be disregarded and the error logged. ## Generic API Emails are parsed using the `generic` API unless another is explicitly specified. This API gets all information from the email recipient (to) address or the query parameters to the HTTPS request. The parameters that can be specified are: - `[incoming-camera-id]`, see above - `folder=[deep_-_folder_-_path]` to set a folder/site prefix. - `_-_` (underscore-dash-underscore) will be converted to `/`, meaning subfolder - `camera=[camera-name]` to set the camera name When the camera name is specified it is recommended to also specify a site-unique `folder` to avoid two cameras getting the same incoming camera id. Either `incoming-camera-id` or `camera` needs to be specified. ### Generic API examples - Example 1 - Incoming ID - SMTP:`camera-841748@alarmfilter.irisity.io` - HTTPS: `http://in.alarmfilter.irisity.io?camera=camera-841748` Will directly correlate the incoming alarm to the camera with the unique incoming camera id `camera-841748` - Example 2 - Folders - SMTP:`folder=Site-ABC&camera=Camera-123@alarmfilter.irisity.io` - HTTPS: `https://in.alarmfilter.irisity.io?folder=Site-ABC&camera=Camera-123` Uses the recommended folder + camera name structure to generate a unique incoming camera id. The incoming camera id name will be `site-abc_-_camera-123` The camera, when created in the system, will be called `Camera 123` and placed in the folder `Site ABC` - Example 3 - Folder levels - SMTP:`folder=US-EAST_-_Connies-Construction&camera=Camera-12@alarmfilter.irisity.io` - HTTPS: `https://in.alarmfilter.irisity.io?folder=US-EAST_-_Connies-Construction&camera=Camera-12` Uses the recommended folder + camera name structure to generate a unique incoming camera id. `_-_` is used to separate two folder levels The incoming camera id will be `us-east_-_connies-construcion_-_camera-12` The camera, when created in the system, will be called `Camera 12` and placed in the folder tree `US EAST` / `Connies Construction` - Example 4 - Shorthands and replacement characters - SMTP:`f_US-EAST_-_Connies-Construction.c_Camera-12@af.irisity.io` - HTTPS: `https://in.alarmfilter.irisity.io?f=US-EAST_-_Connies-Construction&c=Camera-12` Equivalent to Example 3, but with shorthands and replacement characters to support more equipment and to get below 64 characters in length. - Example 5 - Not recommended - SMTP:`camera=Camera-14@alamfilter.irisity.io` - HTTPS: `http://in.alarmfilter.irisity.io?camera=Camera-14` The above example will generate the unique incoming ID using *only* the camera name, meaning that when another `Camera-14` is added to the system, the results will be unpredictable. ## Hikvision-1 The `hikvision-1` has been created to deal with the fact that many Hikvision NVRs and DVRs are unable to specify different Recipient (to) email addresses for different connected cameras. For Hikvision *NVRs*, please use the [Generic API](docId\:S_xm-gAH1-JisvoadcQbz) documentation above. It uses the parameters specified by the user, as well as convention-based metadata set by Hikvision in alarm clip file names and the email body to generate a unique incoming camera id. The supported parameters are - `api=hikvision-1`, required to select the api - `folder=[deep__folder__path]` to set a folder/site prefix. - `_-_` (underscore-dash-underscore) will be converted to `/`, meaning subfolder - `nvr=[nvr-name]` to set the NVR/DVR name - When specified it is recommended to also specify a site-unique `folder` to avoid two cameras getting the same incoming camera id. ### Examples - `api=hikvision-1&folder=Site-ABC&nvr=NVR-123@alarmfilter.irisity.io` - uses the recommended folder + NVR name structure in combination with Hikvision-generated metadata to generate a unique incoming camera id. - the incoming camera id will be similar to `site-abc_-_nvr-123_-_A12` for the case when channel 12 triggered the alarm - the camera when created in the system, will be named similarly to `A12` and placed in the folder `Site ABC` - `api=hikvision-1&folder=US-EAST__Connies-Construction&nvr=NVR-12@alarmfilter.irisity.io` - uses the recommended folder + NVR name structure in combination with Hikvision-generated metadata. - the incoming camera id will be similar to `us_east__connies_construction__nvr_12__a03` for the case when channel 3 triggered the alarm - the camera, when created in the system, will be named similarly to `A03` and placed in the folder tree `US EAST` / `Connies Construction` - `a_hikvision-1.f_US-EAST_-_C-Construction.n_NVR-12@af.irisity.io` - uses alternates since Hikvision devices can be picky with regards to `=` and `&` - uses shorthands to get under a total length of 64, which is required by some Hikvision devices. - Used a shorter folder name, again to get under the 64 character limit (inner-most folder name will be `C Construction` instead of `Connies Construction`) - `api=hikvision-1&nvr=NVR-14` - *Not recommended* - Will generate the incoming ID using *only* the NVR name and Hikvision-generated metadata, meaning that when another `NVR-14` is added to the system, the results will be unpredictable.