What is the Notification API?
It is an interface for notifying external systems about access actions in the ekey bionyx system, providing precise user assignment. This is based on the HTTP(S) requests that are sent directly from the controller. This means that the data is sent in the local network.
Here we would like to show you, what you will get from the Notification API and how to use it.
How to activate the Notification API?
To activate the Notification API go to Settings → Smart Home Connections → Activate Notification API
How are the notifications sent?
-
The structure of the requests 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)
-
Timeout
-
Security
-
Authentication
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 | null |
| Match | 10 |
| Filtered Match* | 20 |
| No Match | 30 |
- schedule, deactivated user;
Result Detail Values
| Name | Value |
|---|---|
| Unknown | null |
| Input Disabled | 10 |
| Time Schedule | 20 |
| No Rule Found | 30 |
| No Input Found | 40 |
| Invalid Input | 50 |
Finger Index
| Name | Value |
|---|---|
| Left Little Finger | -5 |
| Left Ring Finger | -4 |
| Left Middle Finger | -3 |
| Left Index Finger | -2 |
| Left Thumb | -1 |
| None | null |
| Right Thumb | 1 |
| Right Index Finger | 2 |
| Right Middle Finger | 3 |
| Right Ring Finger | 4 |
| Right Little Finger | 5 |
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.
Example Request Bodies
Here we would like to show some examples, how the request bodies will look for certain events.
Positive Match – green
Digital Input
Rejection – Invalid Input – red
Rejection – Unknown Input – green/red
Rejection – Schedule – green/red
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.
