📘 FlexyKey REST API – Developer Integration Guide

Welcome to the FlexyKey REST API.
This API allows third-party developers to integrate booking systems, access control systems, and automation platforms with FlexyKey and Evva AirKey units.

The API provides:

Unit information and IO discovery
Unit control (F1/F2 and X1–X64)
Full IO status monitoring
Webhook-based status notifications
Booking management
Unit logs
And more depending on the unit type

This document explains how to authenticate, how to call the endpoints, and how to interpret responses.

📑 Contents

1. Authentication & Access Control
2. Base URL
3. Data Format
4. IO Model & Unit Structure
- 4.1 Recommended Integration Approach
5. Unit Information
- 5.1 List all units
- 5.2 Get one unit
6. Control API
- 6.1 Control Output
- 6.2 Get IO Status
7. Unit Information Requests
8. ID Entries
9. Unit Settings
10. Unit Sync
11. Tools
12. Webhooks
13. Logs
14. Booking API
15. Best Practices
16. Support

🔐 1. Authentication & Access Control

The FlexyKey API uses HTTP Basic Authentication.
Your FlexyWeb username and password (API-enabled user) must be sent via the Authorization header:

Authorization: Basic base64(username:password)

Swagger and tools like Postman handle this automatically.

Access Requirement
All API calls are executed in the context of the authenticated user.
To use any API function (units, control, status, webhooks, bookings, logs), the user must belong to the same company that owns the target unit or booking object.
If a user does not have rights, the API returns an access error.

🌐 2. Base URL

Production
https://api.flexykey.se/v1/

Swagger documentation
https://api.flexykey.se/v1/swagger

⚙️ 3. Data Format

JSON
UTF-8 encoding
ISO 8601 timestamps, always in UTC for machine-readable timestamp fields

Example:

2025-11-21T10:21:11Z

🔑 4. IO Model & Unit Structure

FlexyKey uses a consistent IO model across the API.

F1, F2 – main unit relays
X1–X64 – expansion relays
IN1–INx – main inputs
IX1–IX64 – expansion inputs

These identifiers are used 1:1 across the API:

Unit API (GET /Units)
Control API (POST /Control)
Status API (GET /Control)
Webhook payloads

This means that IO returned from GET /Units can be used directly for:

Control commands
Status interpretation
Webhook processing

Use globalNumber when referring to IO in integrations.

Examples:

F1 and F2 are the two relays on the main unit
X1 may be relay 1 on expansion module 1
X5 may be relay 1 on expansion module 2
IX1 may be input 1 on expansion module 1

The Unit API returns both:

localNumber – physical/local position on that board or expansion
globalNumber – API-wide identifier used in Control and Status

For example:

        {
        "localNumber": 1,
        "globalNumber": "X5",
        "description": "Alarm output"
        }
    

Here:

localNumber = 1 means it is relay 1 on that specific expansion module
globalNumber = X5 means this is the identifier your integration uses in the API

🧠 4.1 Recommended Integration Approach

Call GET /Units to discover the available IO structure for the unit
Store or map the globalNumber values you need
Use those values in POST /Control
Monitor state through GET /Control or webhooks

Always use globalNumber when interacting with IO.
Use localNumber only for display or mapping to physical terminals and labels.

Do not assume that all units have expansion modules. Some units only expose main relays and main inputs, while others may include WEXP or other expansion types.

📦 5. Unit Information

The Unit API allows applications to:

Retrieve unit metadata
Discover available relays and inputs
See connected expansion modules
Discover configured sensors
Discover available counters and their default mapping
Map local IO positions to API-wide identifiers

This endpoint should normally be the first step in an integration, because it tells you which IO names are valid for each unit.

The Unit API may also include sensors and counters collections. These are metadata/discovery structures and should be used to understand which sensors and counters are available for a unit, how they are identified, and how values should be interpreted.

5.1 Example — List all units

GET

https://api.flexykey.se/v1/units

Response example

        [
        {
        "unitId": 99998,
        "unitType": "FlexyKey",
        "serialnumber": "067530215131204",
        "ownPhoneOrID": "071XXXXXX58819",
        "name": "fkv3 test 2 S.kontor",
        "softVersion": "09.15",
        "unitInfo": "Maccess 09.15 Sn: 067530215131204 SIMCOM_SIM7600E LE11B03SIM7600M21-A T=31 Rssi=25 ESP32-D0WD-V3 F:16 R:4 RssiW=-62 CN:WIFI Build Feb 17 2026 FKV3 Gate",
        "unitNote": "071XXXXXX58819",
        "timezoneId": "W. Europe Standard Time",
        "timezoneInfo": "(UTC+01:00) Amsterdam, Berlin, Bern, Rom, Stockholm, Wien",
        "created": "2025-05-27T14:36:38Z",
        "relays": [
        {
        "localNumber": 1,
        "globalNumber": "F1",
        "description": "Grind"
        },
        {
        "localNumber": 2,
        "globalNumber": "F2",
        "description": "Dörr"
        }
        ],
        "inputs": [
        {
        "localNumber": 1,
        "globalNumber": "IN1",
        "description": "Linjedetektor"
        },
        {
        "localNumber": 2,
        "globalNumber": "IN2",
        "description": "Magnetkontakt"
        }
        ],
        "expansions": []
        },
        {
        "unitId": 99992,
        "unitType": "FlexyKey",
        "serialnumber": "198234122677736",
        "ownPhoneOrID": "071XXXXXX4396",
        "name": "BDD Demo enhet",
        "softVersion": "09.15",
        "unitInfo": "Maccess 09.15 Sn: 198234122677736 SIMCOM§SIM7600E LE20B04SIM7600M21-A T=31 Rssi=25 ESP32-D0WD-V3 F:16 R:4 RssiW=0 CN:GSM Build Dec  4 2025 FKV3 Gate",
        "unitNote": null,
        "timezoneId": "W. Europe Standard Time",
        "timezoneInfo": "(UTC+01:00) Amsterdam, Berlin, Bern, Rom, Stockholm, Wien",
        "created": "2025-09-30T12:35:55Z",
        "relays": [
        {
        "localNumber": 1,
        "globalNumber": "F1",
        "description": "Siren"
        },
        {
        "localNumber": 2,
        "globalNumber": "F2",
        "description": "Dörr"
        }
        ],
        "inputs": [
        {
        "localNumber": 1,
        "globalNumber": "IN1",
        "description": "Nyckelbrytare"
        },
        {
        "localNumber": 2,
        "globalNumber": "IN2",
        "description": "Kolvavkänning"
        }
        ],
        "expansions": [
        {
        "number": 1,
        "type": "WEXP",
        "description": "Objekt 1",
        "macAddress": "2c:bc:bb:17:b3:48",
        "hexAddress": "0",
        "relays": [
        {
        "localNumber": 1,
        "globalNumber": "X1",
        "description": "Larm till"
        },
        {
        "localNumber": 2,
        "globalNumber": "X2",
        "description": "Larm från"
        }
        ],
        "inputs": [
        {
        "localNumber": 1,
        "globalNumber": "IX1",
        "description": "IX1"
        },
        {
        "localNumber": 2,
        "globalNumber": "IX2",
        "description": "IX2"
        },
        {
        "localNumber": 3,
        "globalNumber": "IX3",
        "description": "IX3"
        },
        {
        "localNumber": 4,
        "globalNumber": "IX4",
        "description": "IX4"
        }
        ]
        },
        {
        "number": 2,
        "type": "WEXP",
        "description": "Objekt 2",
        "macAddress": "40:22:d8:f4:63:70",
        "hexAddress": "1",
        "relays": [
        {
        "localNumber": 1,
        "globalNumber": "X5",
        "description": "Dörr"
        },
        {
        "localNumber": 2,
        "globalNumber": "X6",
        "description": "Element"
        }
        ],
        "inputs": [
        {
        "localNumber": 1,
        "globalNumber": "IX5",
        "description": "IX5"
        },
        {
        "localNumber": 2,
        "globalNumber": "IX6",
        "description": "IX6"
        },
        {
        "localNumber": 3,
        "globalNumber": "IX7",
        "description": "IX7"
        },
        {
        "localNumber": 4,
        "globalNumber": "IX8",
        "description": "IX8"
        }
        ]
        },
        {
        "number": 16,
        "type": "OSDP",
        "description": "Läsare",
        "macAddress": "00:00:00:00:00:01",
        "hexAddress": "F",
        "relays": [],
        "inputs": []
        }
        ]
        }
        ]
    

Units without expansion modules will have an empty expansions array.

Different expansion types may expose different capabilities. For example, a WEXP module may contain relays and inputs, while another module type may contain no IO at all.

5.2 Example — Get information about one specific unit

GET

https://api.flexykey.se/v1/units/4132

The response structure is the same as in the list endpoint, but for one unit only.

🔧 6. Control API

The Control API allows developers to:

Control relays (F1, F2) on the main unit
Control up to 64 extended outputs (X1–X64)
Send ON / OFF / pulse commands
Retrieve full IO status (inputs and outputs)
Reference units by unitId or serialNumber

🚀 6.1 Control Output

POST /Control
Send a control command to a FlexyKey unit.

URL:

https://api.flexykey.se/v1/Control

Request body (JSON)
Specify either unitId or serialNumber.
outputNumber can be F1, F2 or X1–X64.
outputAction can be ON, OFF or a pulse value in seconds, 1–99999 (only number, no unit).

Example 1 — Control F1 ON

        {
        "unitId": 3023,
        "outputNumber": "F1",
        "outputAction": "ON"
        }
    

Example 2 — Pulse X33 for 60 seconds

        {
        "serialNumber": "040530585131396",
        "outputNumber": "X33",
        "outputAction": "60"
        }
    

Response:

        {
        "status": "OK",
        "unitId": 3023,
        "outputNumber": "F1",
        "outputAction": "ON",
        "messageId": null
        }
    

📡 6.2 Get IO Status

GET /Control
Retrieve the current IO state of a unit.

By unitId:

https://api.flexykey.se/v1/Control?unitId=3023

By serial:

https://api.flexykey.se/v1/Control?serialNumber=040530585131396

Response example:

        {
        "unitId": 3023,
        "serialNumber": "040530585131396",

        "statusTimestamp": "2025-11-21 08:14:50",
        "statusTimestampIso": "2025-11-21T08:14:50Z",

        "rawStatus": "ASTAT:00----,10,--------------------------------0000--------------------00000000, T1=-- T2=-- T3=-- T7600=42",

        "inputs": [
        { "input": "IN1", "state": "off" },
        { "input": "IN2", "state": "off" }
        ],

        "fOutputs": [
        { "output": "F1", "state": "on" },
        { "output": "F2", "state": "off" }
        ],

        "xOutputs": [
        { "output": "X33", "state": "off" },
        { "output": "X34", "state": "off" },
        { "output": "X35", "state": "off" },
        { "output": "X36", "state": "off" },
        { "output": "X57", "state": "off" },
        { "output": "X58", "state": "off" },
        { "output": "X59", "state": "off" },
        { "output": "X60", "state": "off" },
        { "output": "X61", "state": "off" },
        { "output": "X62", "state": "off" },
        { "output": "X63", "state": "off" },
        { "output": "X64", "state": "off" }
        ],

        "xInputsStatusTimestamp": "2025-11-21 08:14:50",
        "xInputsStatusTimestampIso": "2025-11-21T08:14:50Z",
        "rawXInputsStatus": "INSTAT:00----,0100------------------------------------------------------------",
        "xInputs": [
        { "input": "IX1", "state": "off" },
        { "input": "IX2", "state": "on" }
        ],

        "isCached": false
        }
    

The status response uses the same global IO identifiers as the Unit API.

7. Unit Information Requests

Some unit information is retrieved by sending approved CHECK commands to the physical unit. These commands perform a roundtrip through the unit communication path and the database. The API therefore does not wait for the unit response.

Recommended flow:

Call GET /RequestUnitInfoTypes to discover approved command types and profiles
Call POST /RequestUnitInfo to queue one command or one pre-built profile
Read the result later using GET /UnitMessages or the relevant status endpoint, for example GET /Control

All endpoints use the same Basic Authentication and company/unit access control as the rest of the API.

7.1 GET /RequestUnitInfoTypes

GET /v1/RequestUnitInfoTypes
Returns the public command catalog: approved individual commands and pre-built profiles. Only commands that are visible and enabled in the catalog are returned.

URL:

GET https://api.flexykey.se/v1/RequestUnitInfoTypes

Example response:

        {
        "commands": [
        {
        "typeName": "CHECKASTAT",
        "description": "Read input and output status.",
        "isMultiMessage": false,
        "hydrates": [ "Control.status" ],
        "defaultCacheSeconds": 10,
        "rateLimitMax": 3,
        "rateLimitIntervalSeconds": 60
        },
        {
        "typeName": "CHECKTEMP",
        "description": "Read current temperature.",
        "isMultiMessage": false,
        "hydrates": [ "Control.temperatures" ],
        "defaultCacheSeconds": 10,
        "rateLimitMax": 3,
        "rateLimitIntervalSeconds": 60
        }
        ],
        "profiles": [
        {
        "profileName": "controlStatusFull",
        "description": "Full Control.Status refresh.",
        "typeNames": [ "CHECKASTAT", "CHECKCOUNTERS", "CHECKTEMP", "CHECKSYS" ],
        "cacheSeconds": 300,
        "rateLimitMax": 4,
        "rateLimitIntervalSeconds": 3600
        }
        ]
        }
    

Current public command types:

CHECKASTAT - input and output status, older compatibility format
CHECKSTATUS - FKV2 input and output status
CHECKCOUNTERS - input counters
CHECKTEMP - current temperature response
CHECKSYS - system information
CHECKTIME - unit time and uptime information
CHECKEXP - expansion unit information; may return several response messages
CHECKCALSTAT - calendar status
CHECKSALOFFICEMODE - Sallis lock office mode status
CHECKOUTPUTCAL - calendars connected to outputs/locks
CHECKINPUTCAL - calendars connected to inputs
CHECKESPNOWMAC - ESP-NOW MAC address information
CHECKWEXP - WEXP unit information

Current public profiles:

controlStatusFull - CHECKASTAT, CHECKCOUNTERS, CHECKTEMP, CHECKSYS
controlStatusMedium - CHECKASTAT, CHECKCOUNTERS, CHECKTEMP

7.2 POST /RequestUnitInfo

POST /v1/RequestUnitInfo
Queues one approved command or one approved profile for a unit. Use either unitId or serialNumber, and either typeName or profile.

The endpoint is asynchronous. A successful response means the command was accepted for queuing, not that the unit has already answered.

Request body - one command:

        {
        "unitId": 4053,
        "typeName": "CHECKTEMP"
        }
    

Request body - profile:

        {
        "serialNumber": "194232156360400",
        "profile": "controlStatusMedium"
        }
    

Example response:

        {
        "status": "ACCEPTED",
        "unitId": 4053,
        "serialNumber": "194232156360400",
        "profile": null,
        "commandCount": 1,
        "queuedCount": 1,
        "commands": [
        {
        "typeName": "CHECKTEMP",
        "status": "QUEUED"
        }
        ]
        }
    

Commands and profiles have configurable cache and rate limits to protect the unit communication path. If a command is skipped because of cache or rate limiting, the command result status indicates that instead of queuing a new command.

7.3 GET /UnitMessages

GET /v1/UnitMessages
Returns latest approved incoming unit information messages for a unit. Leave typeName empty to return all approved response types, or set typeName to filter by a specific command.

Only responses matching visible and enabled commands in the public command catalog are returned. Outgoing commands, internal log messages and unsupported raw device reports are not returned.

Default behavior is latest 20 rows, newest first. Maximum limit is 100.

Examples:

        GET https://api.flexykey.se/v1/UnitMessages?unitId=4053

        GET https://api.flexykey.se/v1/UnitMessages?unitId=4053&typeName=CHECKTEMP

        GET https://api.flexykey.se/v1/UnitMessages?serialNumber=194232156360400&limit=50

Example response:

        [
        {
        "id": 135702354,
        "unitId": 4053,
        "direction": "IN",
        "timestamp": "2026-04-20 18:29:16",
        "timestampIso": "2026-04-20T16:29:16Z",
        "message": "T1=24.1 P1=1000.823 H1=30.886 B1=93 T2=21.8 P2=1025.817 H2=24.861 B2=93",
        "matchedType": "CHECKTEMP"
        }
        ]
    

The timestamp field reflects the database timestamp in Swedish/local database time. Use timestampIso for machine storage, comparison and integration logic.

8. ID Entries

ID entries are the unit access list: phone numbers, PIN codes or tag numbers that can be synchronized to a unit. Use these endpoints to read, create, update or mark entries for deletion on the server.

A changed ID entry is not sent to the physical unit immediately. After changing entries, call POST /UnitSync/PushChanges to push the pending changes to the unit. Use GET /UnitSync/Status afterwards to follow progress, for example in a progress bar.

Important field rules:

unitId is required for all operations
idNumber max length is 20 characters
name and description max length is 25 characters
action must be a valid relay/action value, for example R1, R2 or a valid access group such as G13
codeTag must be 4-7 digits when used
codeTagCalendar may only be set when codeTag contains a valid PIN
validFromIso and validToIso use ISO 8601, for example 2026-04-22T14:00:00+02:00 or 2026-04-22T12:00:00Z

8.1 GET /UnitIdEntries

GET /v1/UnitIdEntries
Returns ID entries for a unit. Supports paging and search.

Search matches idNumber, name, description and action. Partial text is accepted. Leave search empty to return all ID entries for the unit.

        GET https://api.flexykey.se/v1/UnitIdEntries?unitId=2472&limit=10&offset=0

        GET https://api.flexykey.se/v1/UnitIdEntries?unitId=2472&search=adam

limit controls page size. offset is the number of rows to skip. Example: first page offset=0, second page offset=limit.

8.2 POST /UnitIdEntries

POST /v1/UnitIdEntries
Creates one ID entry for a unit. Duplicate idNumber values on the same unit return 409 Conflict.

        {
        "unitId": 2472,
        "idNumber": "0701234567",
        "name": "Adam",
        "description": "Office",
        "action": "R1",
        "codeTag": "",
        "codeTagCalendar": "",
        "validFromIso": "2026-04-22T14:00:00+02:00",
        "validToIso": "2026-04-22T16:00:00+02:00"
        }
    

8.3 PUT /UnitIdEntries/{id}

PUT /v1/UnitIdEntries/{id}
Updates one ID entry. The unitId in the body must match the existing row. Changes to idNumber, action, codeTag, codeTagCalendar, validFromIso or validToIso mark the entry as changed for sync. Changes to name or description do not mark the entry as changed, because those fields are not sent to the unit.

8.4 DELETE /UnitIdEntries/{id}

DELETE /v1/UnitIdEntries/{id}
Marks one ID entry for deletion on the server. The deletion is sent to the physical unit by calling POST /UnitSync/PushChanges.

9. Unit Settings

Unit settings are approved customer-facing settings that can be read and updated on the server. Only settings approved by the public catalog are visible through this API.

A changed setting is not sent to the physical unit immediately. After changing settings, call POST /UnitSync/PushChanges to push pending changes to the unit.

Current public settings include:

DefaultRelayPulse
WifiMode
WifiName
WifiPassword

9.1 GET /UnitSettings/Definitions

GET /v1/UnitSettings/Definitions
Returns the approved public settings and their input rules.

GET https://api.flexykey.se/v1/UnitSettings/Definitions

Example response:

        {
        "items": [
        {
        "setting": "DefaultRelayPulse",
        "description": "Default relay pulse time.",
        "params": [
        { "type": "target", "allowed": ["F1", "F2"], "prefix": "X", "prefixMin": 1, "prefixMax": 64 },
        { "type": "integer", "min": 0, "max": 999999, "unit": "seconds" }
        ]
        },
        {
        "setting": "WifiMode",
        "description": "WiFi mode.",
        "params": [
        { "type": "enum", "allowed": ["ON", "OFF"] }
        ]
        }
        ]
        }
    

9.2 GET /UnitSettings

GET /v1/UnitSettings
Returns the approved settings rows that currently exist for the selected unit.

GET https://api.flexykey.se/v1/UnitSettings?unitId=2472

Example response:

        {
        "unitId": 2472,
        "items": [
        {
        "setting": "DefaultRelayPulse",
        "params": ["F1", 15]
        },
        {
        "setting": "WifiMode",
        "params": ["ON"]
        }
        ]
        }
    

9.3 PUT /UnitSettings

PUT /v1/UnitSettings
Creates or updates one approved setting for the selected unit. The body format is one setting at a time.

        {
        "unitId": 2472,
        "setting": "DefaultRelayPulse",
        "params": ["F1", 15]
        }
    

Examples:

        {
        "unitId": 2472,
        "setting": "WifiMode",
        "params": ["ON"]
        }

        {
        "unitId": 2472,
        "setting": "WifiName",
        "params": ["min Router"]
        }
    

If a setting is not approved by the public catalog, the API returns 400 Bad Request. After a successful update, call POST /UnitSync/PushChanges to send pending changes to the unit.

10. Unit Sync

Unit Sync sends changed customer data from the server to the physical unit.

Recommended flow:

Create, update or mark ID entries for deletion using /UnitIdEntries, and update settings using /UnitSettings
Call POST /UnitSync/PushChanges
Poll GET /UnitSync/Status until the sync is completed, failed or timed out
If needed, call POST /UnitSync/Abort to stop the active sync and clean pending packets

10.1 POST /UnitSync/PushChanges

POST /v1/UnitSync/PushChanges
Packages changed customer data and queues communication packets to the unit. The endpoint returns immediately and does not wait for the unit to answer.

        {
        "unitId": 2472
        }
    

Example response:

        {
        "status": "ACCEPTED",
        "message": "Unit sync was queued.",
        "unitId": 2472,
        "entryCount": 8,
        "packetCount": 2
        }
    

10.2 GET /UnitSync/Status

GET /v1/UnitSync/Status
Returns the current sync status for a unit. Status responses have a short cache guard, normally 2 seconds.

GET https://api.flexykey.se/v1/UnitSync/Status?unitId=2472

If there is no active sync, the API returns a normal response with message No active unit programming.

10.3 POST /UnitSync/Abort

POST /v1/UnitSync/Abort
Aborts the active unit sync for the unit and clears pending programming packets. Use this when a sync has failed, timed out or must be restarted.

        {
        "unitId": 2472
        }
    

11. Tools

Tools are server-side maintenance endpoints. They do not communicate with the physical unit. Use them only when you intentionally need to adjust what the server considers synchronized or changed.

11.1 POST /Tools/IdEntriesSyncState

POST /v1/Tools/IdEntriesSyncState
Changes the server-side unit sync state for ID entries on one unit. Send id if you want to affect one row. Leave id out if you want to affect all ID entries for the selected unit.

        {
        "unitId": 2472,
        "id": 506757,
        "unitSyncState": "READY_TO_SEND"
        }
    

        {
        "unitId": 2472,
        "unitSyncState": "IDLE_OK"
        }
    

11.2 POST /Tools/UnitSettingsSyncState

POST /v1/Tools/UnitSettingsSyncState
Changes the server-side unit sync state for approved public settings on one unit. Send setting plus params if you want to affect one approved setting. Leave them out if you want to affect all approved settings for the selected unit.

        {
        "unitId": 2472,
        "setting": "DefaultRelayPulse",
        "params": ["F1", 15],
        "unitSyncState": "READY_TO_SEND"
        }
    

        {
        "unitId": 2472,
        "unitSyncState": "IDLE_OK"
        }
    

11.3 POST /Tools/AllUnitDataSyncState

POST /v1/Tools/AllUnitDataSyncState
Macro endpoint that changes the server-side unit sync state for both ID entries and settings on one unit. This endpoint only needs unitId and unitSyncState.

        {
        "unitId": 2472,
        "unitSyncState": "READY_TO_SEND"
        }
    

12. Webhooks

The Webhooks API allows your system to receive HTTP callbacks when a unit reports a status update.

Currently supported event:

control.statusChanged

Important
The event control.statusChanged is triggered when an ASTAT status message is received from the unit.
To receive updates on IO changes, the FlexyKey unit must be configured to report IO changes.

Important
Webhooks require secure communication to be enabled on the FlexyKey unit.
This may or may not be the default setting depending on the unit version and may need to be enabled manually.

A webhook is configured per unitId and event type.

The webhook payload for control.statusChanged uses the same JSON object structure as:

GET /v1/Control

This means you can use the same parsing logic for:

Polling via GET /v1/Control
Push updates via webhook callbacks

12.1 Webhook event payload

When the event control.statusChanged is sent, the payload matches the Control status response and may contain:

unitId
serialNumber
statusTimestamp
statusTimestampIso
rawStatus
inputs
fOutputs
xOutputs
xInputsStatusTimestamp
xInputsStatusTimestampIso
rawXInputsStatus
xInputs
isCached

Example webhook payload

        {
        "unitId": 4818,
        "serialNumber": "009869306621688",
        "statusTimestamp": "2026-03-28 20:49:46",
        "statusTimestampIso": "2026-03-28T19:49:46Z",
        "rawStatus": "ASTAT:0000--,00,0000----------------------------0000--------------------00000000, T1=-- T2=-- T3=-- T7600=28",
        "inputs": [
        { "input": "IN1", "state": "off" },
        { "input": "IN2", "state": "off" },
        { "input": "IN3", "state": "off" },
        { "input": "IN4", "state": "off" }
        ],
        "fOutputs": [
        { "output": "F1", "state": "off" },
        { "output": "F2", "state": "off" }
        ],
        "xOutputs": [
        { "output": "X1", "state": "off" },
        { "output": "X2", "state": "off" },
        { "output": "X3", "state": "off" },
        { "output": "X4", "state": "off" }
        ],
        "xInputsStatusTimestamp": "2026-03-28 20:49:46",
        "xInputsStatusTimestampIso": "2026-03-28T19:49:46Z",
        "rawXInputsStatus": "INSTAT:0000--,0000------------------------------------------------------------",
        "xInputs": [
        { "input": "IX1", "state": "off" },
        { "input": "IX2", "state": "off" },
        { "input": "IX3", "state": "off" },
        { "input": "IX4", "state": "off" }
        ],
        "isCached": false
        }
    

If a unit has no expansion inputs, or if no X-input status is available, the X-input fields may be empty or null:

        "xInputsStatusTimestamp": null,
        "xInputsStatusTimestampIso": null,
        "rawXInputsStatus": null,
        "xInputs": []
    

12.2 GET /Webhooks/Events

GET /v1/Webhooks/Events
Returns the currently supported webhook event types.

Example request

GET https://api.flexykey.se/v1/Webhooks/Events

Example response

        [
        {
        "eventName": "control.statusChanged",
        "description": "Triggered when an ASTAT status message is received from the unit. IO change notifications require the unit to be configured to report IO changes."
        }
        ]
    

12.3 PUT /Webhooks

PUT /v1/Webhooks
Creates or updates a webhook configuration for a specific unitId and event.

This endpoint uses an upsert model:

If no webhook exists for the unit and event, a new webhook is created
If a webhook already exists, it is updated

Request body fields

unitId – required
event – required
callbackUrl – required, absolute HTTP/HTTPS URL
httpMethod – optional, POST, PUT or PATCH
secret – optional, used for HMAC signature
apiKey – optional, sent as X-Api-Key
isActive – optional, 1 or 0

Example request

        PUT https://api.flexykey.se/v1/Webhooks

        {
        "unitId": 4818,
        "event": "control.statusChanged",
        "callbackUrl": "https://example.com/flexykey/webhook",
        "httpMethod": "POST",
        "isActive": 1
        }
    

Example response (created)

        {
        "id": 3,
        "unitId": 4818,
        "event": "control.statusChanged",
        "callbackUrl": "https://example.com/flexykey/webhook",
        "httpMethod": "POST",
        "isActive": 1
        }
    

Notes

Use isActive=0 to temporarily disable a webhook without deleting it
The user must have access rights to the unit
The event name must be one of the values returned by GET /v1/Webhooks/Events

12.4 GET /Webhooks

GET /v1/Webhooks
Returns webhook configuration for a unit.

Required query parameter

unitId

Optional query parameter

event – if provided, returns only the webhook for this event

Example – get all webhooks for a unit

GET https://api.flexykey.se/v1/Webhooks?unitId=4818

Example – get one webhook

GET https://api.flexykey.se/v1/Webhooks?unitId=4818&event=control.statusChanged

Example response

        {
        "id": 3,
        "unitId": 4818,
        "event": "control.statusChanged",
        "callbackUrl": "https://example.com/flexykey/webhook",
        "httpMethod": "POST",
        "isActive": 1,
        "lastAttemptUtc": "2026-03-28T19:49:55Z",
        "lastSuccessUtc": "2026-03-28T19:49:55Z",
        "lastStatusCode": 200,
        "lastError": null,
        "attemptsTotal": 16,
        "successesTotal": 16,
        "failuresTotal": 0,
        "consecutiveFailures": 0,
        "disabledUntilUtc": null
        }
    

12.5 DELETE /Webhooks

DELETE /v1/Webhooks
Deletes a webhook for a specific unitId and event.

Required query parameters

unitId
event

Example request

        DELETE https://api.flexykey.se/v1/Webhooks?unitId=4818&event=control.statusChanged
    

Response
Returns 204 No Content if the webhook was deleted.

12.6 POST /Webhooks/Test

POST /v1/Webhooks/Test
Sends a direct HTTP test call to the configured webhook endpoint for the specified unit and event.

This is useful for:

Verifying that the callback URL is reachable
Verifying that your endpoint accepts the webhook
Checking headers, signature and body format

Request body

        {
        "unitId": 4818,
        "event": "control.statusChanged"
        }
    

Example request

        POST https://api.flexykey.se/v1/Webhooks/Test
        Content-Type: application/json

        {
        "unitId": 4818,
        "event": "control.statusChanged"
        }
    

Example response

        {
        "status": "OK",
        "webhookId": 3,
        "httpStatus": 200
        }
    

Important
The test call sends the same payload structure as GET /v1/Control / status webhook payload.

12.7 How to test webhooks

Recommended test flow

Create a temporary endpoint using a request inspection service such as webhook.site, or use your own HTTPS endpoint
Create or update the webhook using PUT /v1/Webhooks
Verify the configuration using GET /v1/Webhooks
Trigger a test delivery using POST /v1/Webhooks/Test
Inspect the received JSON body and verify that your application can parse it
Finally, trigger a real unit status change and verify that production webhook delivery works as expected

Example test using webhook.site

Open https://webhook.site and copy the generated URL
Use that URL as callbackUrl in PUT /v1/Webhooks
Call POST /v1/Webhooks/Test
Check that the request appears on the webhook.site page

Headers sent with webhook requests

X-Event – event name, for example control.statusChanged
X-UnitId – unit ID
X-Webhook-Test: 1 – present on test deliveries
X-Api-Key – present if configured
X-Signature – present if a secret is configured

Signature
If a webhook secret is configured, the payload is signed and sent in:

X-Signature: sha256=<hex-hmac>

The HMAC is calculated over the raw JSON request body using the configured secret.

12.8 Recommended client behavior

Respond with HTTP 2xx as quickly as possible
Parse the payload using the same model as GET /v1/Control
Use statusTimestampIso and xInputsStatusTimestampIso for storage and ordering
Do not assume that xInputs is always present; units without expansion inputs may return empty X-input fields
Use webhook delivery for real-time updates and use GET /v1/Control only when polling is necessary

13. Logs

FlexyKey logs are available via API for:

Access events
System messages
SMS events
Communication logs

(Evva logs are not available.)

Example — Retrieve logs for a unit

GET

        https://api.flexykey.se/v1/unitlogs/3023?dateFrom=2025-11-18T07:00:00Z&dateTo=2025-11-27T16:00:00Z
    

Response example

        [
        {
        "serverDate": "2025-11-26T19:18:54Z",
        "unitDate": "2025-11-26T19:18:00Z",
        "sourceID": "9000004321",
        "sourceLabel": "Enskild kod larm på",
        "actionLabel": "61",
        "logMsg": "puls på X-utgång via telefon/rfid/tangentbord"
        },
        {
        "serverDate": "2025-11-26T19:19:44Z",
        "unitDate": "2025-11-26T19:18:00Z",
        "sourceID": "9000001234",
        "sourceLabel": "- Saknas -",
        "actionLabel": "-",
        "logMsg": "numret finns inte registrerat"
        },
        {
        "serverDate": "2025-11-27T07:49:46Z",
        "unitDate": "2025-11-27T07:49:00Z",
        "sourceID": "Informationslogg",
        "sourceLabel": "--",
        "actionLabel": "--",
        "logMsg": "Omstart av programvara."
        }
        ]
    

14. Booking API

The Booking API allows applications to:

Create bookings
Delete bookings
Query bookings
Assign phone, keypad code, or RFID credentials (depending on unit type)

Example — Create a booking

        {
        "bookingObjectId": 123,
        "startDate": "2025-11-21T09:00:00Z",
        "endDate": "2025-11-21T10:00:00Z",
        "phone1": "+46701234567"
        }
    

Successful responses include a unique bookingId.

15. Best Practices

Always check HTTP status codes
Use the ISO timestamps (statusTimestampIso, xInputsStatusTimestampIso) for storage and ordering
Use GET /Units to discover and cache unit metadata such as IO, sensors and counters; do not call it before every Control or Status command
Always use globalNumber values such as F1, X33 or IX2 in your integration logic
Use webhook delivery for real-time updates whenever possible
Use GET /Control when polling is necessary
Use POST /RequestUnitInfo to request approved CHECK information from the unit, then read the later response using GET /UnitMessages or the relevant status endpoint
Do not repeatedly request full unit information profiles; they have longer cache and rate limits because they use the unit communication path
After changing ID entries, use POST /UnitSync/PushChanges and poll GET /UnitSync/Status until the sync is completed
Use /Tools endpoints only for server-side maintenance, for example when replacing a unit or resending entries
If polling is necessary: do not poll status too frequently (recommended 5–10 seconds)
If polling is necessary: do not poll status too long; in most cases 2–5 status requests after a control command are sufficient.
Do not assume that X-inputs are always present
Pulse commands (“60”) return to OFF when expired
Treat X-outputs case-insensitively (“x33” = “X33”)
Always use HTTPS

16. Support

FlexAccess AB
https://flexaccess.se
support@flexaccess.se

Please provide:

Your API username
Unit serial number
Example request + response
Approximate timestamp (UTC)