# Documentation Notification API

**URL:** <https://developer.ekey.net/t/documentation-notification-api/70>\
**Category:** Notification API\
**Created:** [November 4, 2025, 7:30am UTC](https://developer.ekey.net/t/documentation-notification-api/70 "2025-11-04T07:30:41Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![christoph.deimel](https://dub1.discourse-cdn.com/flex017/user_avatar/developer.ekey.net/christoph.deimel/32/123_2.png) [@christoph.deimel](https://developer.ekey.net/u/christoph.deimel)\
**Post date:** [November 4, 2025, 7:30am UTC](https://developer.ekey.net/t/documentation-notification-api/70/1 "2025-11-04T07:30:42Z")

</div>

# How to activate the Notification API?

To activate the Notification API go to Settings → Smart Home Connections → Activate Notification API

 ![image](https://europe1.discourse-cdn.com/flex017/uploads/ekey/original/1X/74936a8424ec2241e07caed88cde9a18ddf56311.png) ![image](https://europe1.discourse-cdn.com/flex017/uploads/ekey/original/1X/85c03a1a6a9358c63cf2c84d732b502660fbfe76.png) ![image](https://europe1.discourse-cdn.com/flex017/uploads/ekey/original/1X/d2ac3535b56f1827d6bfa06854da74f2ec545c2f.png)

**Please note our [security implementation guidelines](https://developer.ekey.net/t/security-details/22#ekey-bionyx-embedded-device-api-client-4)!**

# How are the notifications sent?

The structure of the request is determined by ekey

- Directory path

- JSON content

- POST method

Customer/integrator can determine some basics

- Basic URL (host name, port)

- MDNS also possible (mdns-name.local)

- Customer has to implement HTTP/S server

- Timeout

- Security

- Authentication

All notifications triggered by finger will have URL/api/notification/finger and all notifications triggered by input will have URL/api/notification/input in the address.

 ![image](https://europe1.discourse-cdn.com/flex017/uploads/ekey/original/1X/06fc6705884d97b1ae4d9bf48fac0b3a2365dbd7.png)

# When are notifications sent?

- Finger was recognised

- Rule exists

- Rule present but filter active (schedule, deactivated user → user without function)

- No rule available

- Finger was not recognised

- However, match quality of the finger image must be given (fingertip, etc. are not notified)

- Digital input is triggered

# Content of Notification Body

| **Name** | **Value** | **Description/Example** | **Data type** |
| --- | --- | --- | --- |
| Time and Date | time | 2024-03-27T10:22:58Z | string |
| Input Typde | type | 10 | Integer |
| Result | result | 10 | Integer |
| Result Detail | detail | 10 | Integer |
| Executing Device | ctlDevId | 4500080101000001 | String |
| Acquiring Device | acqDevId | 4500070101000001 | String |
| User ID | userId | tKlLpvUa | String |
| Finger Index | fingerIndex | 2 | Integer |
| Digital Input | inputNumber | 1 | Integer |
| Input Trigger | trigger | posedge | String |

The time is specified in UTC.

# Input Type Values

| **Name** | **Value** |
| --- | --- |
| Finger | 10 |
| Digital Input | 20 |

# Result Values

| **Name** | **Value** |
| --- | --- |
| Unknown | 0 |
| Match | 10 |
| Filtered Match\* | 20 |
| No Match | 30 |

- schedule, deactivated user;

# Result Detail Values

| **Name** | **Value** |
| --- | --- |
| Unknown | 0 |
| Input Disabled | 10 |
| Time Schedule | 20 |
| No Rule Found | 30 |
| No Input Found | 40 |
| Invalid Input | 50 |
| Time Limitation | 60 |

# Finger Index

| **Name** | **Value** |
| --- | --- |
| Left Little Finger | -5 |
| Left Ring Finger | -4 |
| Left Middle Finger | -3 |
| Left Index Finger | -2 |
| Left Thumb | -1 |
| None | 0 |
| Right Thumb | 1 |
| Right Index Finger | 2 |
| Right Middle Finger | 3 |
| Right Ring Finger | 4 |
| Right Little Finger | 5 |

If a ‘null’ is returned instead of a value, then no further information is available.

# System Export – Mapping

To see the mapping of your notifications request body, you will get a .JSON file to export from the ekey bionyx app. In that file there are your current users and devices with names and IDs listed.

 ![image](https://europe1.discourse-cdn.com/flex017/uploads/ekey/original/1X/9c9093ca294c3ea7c88c4aabf90409cebe1d7f7e.png)

# Example Request Bodies

Here we would like to show some examples, how the request bodies will look for certain events.

_Positive Match – green_

```js
{
  "type": 10,
  "result": 10,
  "detail": null,
  "time": "2024-05-29T15:47:42Z",
  "ctlDevId": "4500080101000035",
  "acqDevId": "4500070101000025",
  "params": {
    "userId": "tKlLpvUa",
    "fingerIndex": 2
  }
}

```

_Digital Input_

```js
{
  "type": 20,
  "result": 20,
  "detail": 10,
  "time": "2024-05-06T09:16:43Z",
  "ctlDevId": "4500080101000035",
  "acqDevId": "4500080101000035",
  "params": {
    "inputNumber": 1,
    "trigger": "posedge"
  }
}

```

_Rejection – Invalid Input – red_

```js
{
  "type": 10,
  "result": 30,
  "detail": 50,
  "time": "2024-05-29T10:31:14Z",
  "ctlDevId": "4500080101000035",
  "acqDevId": "4500070101000025",
  "params": {
    "userId": null,
    "fingerIndex": null
  }
}

```

_Rejection – Unknown Input – green/red_

```js
{
  "type": 10,
  "result": 30,
  "detail": 40,
  "time": "2024-05-29T10:15:16Z",
  "ctlDevId": "4500080101000035",
  "acqDevId": "4500070101000025",
  "params": {
    "userId": null,
    "fingerIndex": null
  }
}

```

_Rejection – Schedule – green/red_

```js
{
  "type": 10,
  "result": 20,
  "detail": 20,
  "time": "2024-05-29T15:47:34Z",
  "ctlDevId": "4500080101000035",
  "acqDevId": "4500070101000025",
  "params": {
    "userId": "tKlLpvUa",
    "fingerIndex": 2
  }
}

```

# Testing

For testing the whole process, you can use the following site in your browser. There you will get a predetermined URL and you just have to copy it into the Notification API URL area.

 ![image](https://europe1.discourse-cdn.com/flex017/uploads/ekey/original/1X/a5ad5ecd528ad04c970543c67bdbb5ea75ffd51b.png)

> **[Webhook.site - Test, transform and automate Web requests and emails](https://webhook.site)**
>
> Instantly generate a free, unique URL and email address to test, inspect, and automate (with a visual workflow editor and scripts) incoming HTTP requests and emails