ASSA ABLOY Global Solutions Web API

Web API
Valid from Revision

DocNo: 61 1100 080 2019-08-19 59
Approved by: Halvor Aase ECN: EC001067019
61 1100 080
WEB API
Author(s): Magnus Persson, Amarjit Singh, Amit Sharma, Per Hedberg, Miraz Zaidi, Filip Johansson
/svn/documents/1100 - Utvecklingsavdelningen/61/61 1100 080 - AAH Web API/*.tex

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
TABLE OF CONTENTS
1 Summary 8
2 Terminology 8
3 Security and authentication 9

3.1 Encrypted communication channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2 Initial authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3 Authentication of requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4 Protocol 10
4.1 Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.2 URL structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.3 Request body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.3.1 Basic data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.3.2 Date and time representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.3.3 Character encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.4 Status codes and error objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.4.1 Detailed error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.5 Request signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.5.1 HTTP verb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.5.2 Content-MD5 header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.5.3 Content-Type header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.5.4 Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.5.5 Canonicalized headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.5.6 Canonicalized resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.5.7 Client and server time in requests . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.6 Session life-time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.7 Future expansions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.8 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5 Resources 19
5.1 /alarmTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.1.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.2 /alarmTypes/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.2.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.2.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.3 /alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

c ASSA ABLOY Page 2/102
Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.3.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.3.2 Query parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.4 /alarms/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.4.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.4.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.5 /blockingGroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.5.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.5.3 /Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.6 /blockingGroups/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.6.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.6.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.7 /callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.7.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.7.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.8 /callback/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.8.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.8.2 Query parameters for GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.8.3 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.9 /cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.9.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.9.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.9.4 Query parameters for POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.10 /cards/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.10.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.10.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.10.3 Card formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.10.4 Encoding and reading card on encoder . . . . . . . . . . . . . . . . . . . . . . . 27
5.11 /counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.11.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.11.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.12 /doors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.12.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.13 /doors/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.13.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.13.2 Normal properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.13.3 Door states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

5.13.4 Command properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.14 /encoders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.14.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.15 /encoders/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.15.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.16 /mobileaccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.16.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.17 /mobileaccess/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.17.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.17.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.18 /nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.18.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.19 /nodes/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.19.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.19.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.19.3 Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.19.4 Function object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.20 /profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.20.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.20.3 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.21 /profiles/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.21.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
5.21.3 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.21.4 BLE specific properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.21.5 LCX specific properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.22 /resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.22.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.22.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.23 /resources/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.23.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.23.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.24 /sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.24.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.24.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.25 /sessions/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.25.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.26 /timeSchedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.26.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.26.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.27 /userGroups/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.27.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.27.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.27.3 Doors and user groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.28 /users/{id} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.28.1 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
5.28.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
5.28.3 Extended expire time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
6 Reference implementation 40
6.1 AAHWebService.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
7 Use cases 44
7.1 Session management and request signatures . . . . . . . . . . . . . . . . . . . . . . . . 44
7.1.1 Create a session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
7.1.2 Create a session with extended rights . . . . . . . . . . . . . . . . . . . . . . . 44
7.1.3 Sign a request without a body . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
7.1.4 Sign a request with a body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
7.1.5 Terminate a session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
7.2 Create and read user information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
7.2.1 Create a new user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
7.2.2 Modify information for existing user . . . . . . . . . . . . . . . . . . . . . . . . 47
7.3 Create and read guest cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
7.3.1 Encode a new card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
7.3.2 Encode a new card with track 2 data . . . . . . . . . . . . . . . . . . . . . . . . 49
7.3.3 Read the contents of an encoded card . . . . . . . . . . . . . . . . . . . . . . . 50
7.3.4 Read serial number of an empty card . . . . . . . . . . . . . . . . . . . . . . . 50
7.3.5 Prepare a card for auto-update . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.3.6 Prepare guest card for third party encoding . . . . . . . . . . . . . . . . . . . . 51
7.3.7 Prepare joiner cards for third party encoding . . . . . . . . . . . . . . . . . . . 52
7.3.8 Prepare staff card for third party encoding . . . . . . . . . . . . . . . . . . . . . 53

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7.3.9 Issue a card that is a joiner to another card . . . . . . . . . . . . . . . . . . . . . 54

7.3.10 Issue a card that overrides another card . . . . . . . . . . . . . . . . . . . . . . 55
7.3.11 Prepare a card for auto-update and connect metadata to the card . . . . . . . . . 56
7.4 Create guest card advanced . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.4.1 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.4.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.5 Create mobile key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
7.5.1 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
7.5.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
7.5.3 Create mobile key with override . . . . . . . . . . . . . . . . . . . . . . . . . . 61
7.5.4 Create mobile key as joiner key . . . . . . . . . . . . . . . . . . . . . . . . . . 62
7.5.5 Create mobile key with label, description and url meta data . . . . . . . . . . . . 63
7.5.6 Create mobile key for staff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
7.5.7 Create and return mobile key credential . . . . . . . . . . . . . . . . . . . . . . 64
7.6 Create and read staff cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
7.6.1 Encode a new card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
7.6.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
7.6.3 Read the contents of an encoded staff card . . . . . . . . . . . . . . . . . . . . . 67
7.6.4 Prepare a staff card for auto-update . . . . . . . . . . . . . . . . . . . . . . . . 67
7.7 Modify cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
7.7.1 Change the doors of an issued card . . . . . . . . . . . . . . . . . . . . . . . . . 68
7.7.2 Deactivate a card at a specific time . . . . . . . . . . . . . . . . . . . . . . . . . 69
7.7.3 Extend the access time for a card . . . . . . . . . . . . . . . . . . . . . . . . . . 69
7.7.4 Cancel a card that was misplaced . . . . . . . . . . . . . . . . . . . . . . . . . 69
7.7.5 Update joiners of a card automatically . . . . . . . . . . . . . . . . . . . . . . . 70
7.8 User groups and guest cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
7.8.1 Create a user group without uniform access . . . . . . . . . . . . . . . . . . . . 71
7.8.2 Issue a card using doors from a user group . . . . . . . . . . . . . . . . . . . . . 71
7.8.3 Create a user group with uniform access . . . . . . . . . . . . . . . . . . . . . . 72
7.8.4 Create a user with extended expire time and uniform access . . . . . . . . . . . 72
7.8.5 Issue a card to a user with extended expire time and uniform access . . . . . . . 73
7.8.6 Change the doors for all cards within a user group with uniform access . . . . . 73
7.8.7 Change group of a user within a group with uniform access . . . . . . . . . . . . 74
7.9 Find cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
7.9.1 Find the card of a card holder . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
7.9.2 Get the pending image for a specific serial number . . . . . . . . . . . . . . . . 75
7.9.3 Get pending images for valid cards . . . . . . . . . . . . . . . . . . . . . . . . 75

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7.10 Door groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

7.10.1 Find out which doors that belong to a door group . . . . . . . . . . . . . . . . . 76
7.11 Network nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7.11.1 Request information about all nodes in the network at once . . . . . . . . . . . . 77
7.11.2 Request information about a single node in the network . . . . . . . . . . . . . . 77
7.12 Sending commands to doors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7.12.1 Unlock a door . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
7.12.2 Set stand open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
7.12.3 Clear stand open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
7.13 Sending checkout commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
7.13.1 Check out all guests from a door . . . . . . . . . . . . . . . . . . . . . . . . . . 79
7.13.2 Check out all guests from multiple doors . . . . . . . . . . . . . . . . . . . . . 79
7.13.3 Check out all guests with grace time . . . . . . . . . . . . . . . . . . . . . . . . 80
7.13.4 Check out an individual guest card . . . . . . . . . . . . . . . . . . . . . . . . . 80
7.13.5 Check out an individual mobile key . . . . . . . . . . . . . . . . . . . . . . . . 80
7.14 Set-up callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
7.14.1 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
7.14.2 EMI Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.14.3 Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
7.14.4 Doors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7.14.5 Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7.14.6 Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7.14.7 Multiple resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.14.8 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.15 Remove callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.16 Get callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.17 List available resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
7.18 List available parameters and properties for the cards resource . . . . . . . . . . . . . . 99
7.19 List available resources with details . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8 References 100
9 Document History 101

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
1 SUMMARY
The ASSA ABLOY Global Solutions Web API is an interface to Visionline systems through a secure
channel. Through this interface, it is possible to issue guest and staff cards, modify existing guest cards,
create users and modify which group the user belongs to.
The interface is implemented as a web service, using the principles of REST and formatting requests
and responses as JSON. The use of these standardized technologies makes it easy to understand and
implement for third-party developers, and simplifies integration with existing network equipment.
The transport protocol is HTTPS (HTTP over SSL), which is a well-tested, secure solution and allows
exchanging security credentials and cryptographic keys without additional security measures. Our secure
connection requires TLS1.0 or better protocol. We have removed the support for SSL2 and SSL3.
The functionality of the Web API is currently a subset of the PMS Plus Protocol [1], combined with new
features not present in the old protocol. For example, it is not possible to issue staff cards, rent safes,
or set rooms in Alarms Disabled Mode with the current implementation. Features of the Web API that
are not present in the PMS Plus Protocol, apart from increased security, include monitoring of network
nodes and obtaining the logical structure of the network.
2 TERMINOLOGY
Client - In the context of this API, a computer controlled by an entity that is external to the Visionline
system but has a network connection to the Visionline server.
HTTP - Hypertext Transfer Protocol, an application protocol for distributed media.
HTTPS - Hypertext Transfer Protocol Secure, HTTP encrypted with SSL.
JSON - JavaScript Object Notation, a text-based standard for data representation.
REST - Representational State Transfer, an architectural style for distributed systems.
Serial number - In the context of smart cards, a unique number that was written to the card during
manufacturing and that cannot be modified.
Server - In the context of this API, the computer that hosts the Visionline production server software.
SSL - Secure Socket Layer, a cryptographic protocol. Our secure connection requires TLS1.0 or better
protocol.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
3 SECURITY AND AUTHENTICATION
3.1 Encrypted communication channel

The communication between the client and the server relies on SSL in order to be protected against
eavesdropping and manipulation by a third party. This allows the exchange of sensitive information,
such as passwords and access keys, between the client and the server without additional considerations.
3.2 Initial authentication

Before a client may access most parts of this API on the server, it must be authenticated. The credentials
consists of a username, a password, and in some cases a key card. With the proper credentials, the server
agrees to create a session and returns a session ID and a session access key. Section 5.24 contains details
about the authentication request and response.
A session has a limited life-time and the server may instruct the client to re-authenticate in order to
establish a new session (see section 4.4 and 4.6). An instruction to re-authenticate happens as a response
to a request, and the last request will not have been carried out in this case. The client will need to create
a new session and then re-send the last request.
3.3 Authentication of requests

The session access key that was returned by the server is used by the client to create a signature for
every request that it sends to the server. In this way, the client proves to the server that it has the correct
key, without having to send the key with every request. By not sending the key repeatedly, it makes
cryptographic attacks a lot harder. By including the current time in the signature, and by imposing a
time-limit on the session, the server will also prevent old sessions from being replayed by an attacker.
The request signature is similar to the mechanism employed by Amazon S3, described in the AWS
documentation [3]. HMAC-SHA1 is used for signing a combination of the request method, URL, and
some specific request headers. The signature procedure is described in section 4.5.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
4 PROTOCOL
The Web API has been designed according to the principles of Representational State Transfer (REST)
and is implemented as a Web Service. The requests must be formatted according to HTTP/1.1 [2]. The
HTTP methods GET, POST, PUT and DELETE are used to retrieve and modify the resources that are
defined by the API, and the body of these HTTP requests are encoded in JSON format.
4.1 Operations
Resources can be divided into two types:
Basic resources - Entities that can be read or modified using a single request.
Collection resources - Entities that represents a collection of basic resources.
In principle, all resources could be accessed using the following actions:
• Read all properties of a resource using a GET request.
• Read all resources of a certain type by using a GET request on a collection resource.
• Create a new resource with a PUT request, given that the client supplies the ID of the new resource.
• Create a new resource with a POST request to a collection resource, allowing the server to assign
the ID of the new resource.
• Replace all properties of an existing resource by using a PUT request.
• Modify one or more properties of an existing resource by using a POST request.
• Remove a resource using a DELETE request.
However, the API imposes various restrictions of certain resources. These restrictions may vary depend-
ing on the permissions associated with the authenticated user.
• Some properties of a resource are left out in a GET request.
• The user is not allowed to obtain the full list of resources within a collection.
• Some resources cannot be created through the Web API.
• Some resources cannot be created using a PUT request, since the system must assign the resource
name.
• Some resources cannot be replaced using a PUT request, since some properties are not allowed to
be modified by the user.
• Some resources cannot be removed by the user.
The complete set of valid operations for each type of resource is described in section 5.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
4.2 URL structure

The resources are identified by URLs which are formed by combining transport protocol, server name,
base URL of the web service, a version identifier, and the relative path of the resource. The transport
protocol is HTTPS and the version identifier of this API is v1. If the server has the name dc.example.
com and the web service has been configured to serve requests below the path /api, a card with id
135792 can be reached using the URL https://dc.example.com/api/v1/cards/135792.
A URL may also have a set of parameters, which then are supplied as standard query string, i.e. a list of
key=value pairs separated by & and appended to the URL with a ?, e.g. https://dc.example.com/
api/v1/cards?validTime=20130110T0900&cardHolder=jdoe.
Throughout this document, these values will be used in examples, and it should be replaced by values
derived from configuration of each particular facility.
The URL must be percent-encoded according to RFC 3986 [4]. The characters / and ? must not be
encoded when they separate different path segments. However, they must be encoded when they are
used within a path segment, e.g. when they are part of the ID of a resource.
4.3 Request body

The body of all requests to the server and responses from the server will be in JavaScript Object Notation
(JSON) and the HTTP header Content-Type must be set to application/json charset=utf-8.
When accessing a resource (both reading and modifying), the whole or part of the resource will be
included in the response. The response will be either a JSON object, containing at least a member named
id, or a list of objects of the same type, where all objects contains at least a member named id. E.g. when
creating a new card resource, using a POST request to the /api/v1/cards resource, the system will
assign an id to the card and return this in the JSON object representing the newly created resource.
4.3.1 Basic data types

The JSON objects may contain strings, integers and Boolean values (true or false). Values that hold the
id:s of other resources are represented as strings. Date and time values are represented as strings.
4.3.2 Date and time representation

When dates and times are contained in a request, they must be formatted according to ISO 8601 and
in most cases in local time, i.e. without time zone designators. Some exceptions exist, where the time
instead must be represented in UTC. When the server returns dates and times, they will also be formatted
according to ISO 8601 local time. The server will adjust some timestamps, e.g. by applying margins
for expire times or rounding off seconds and minutes, and the time actually used by the server is then
returned in the response.
4.3.3 Character encoding

The format of the request and response bodies are expected to be encoded in UTF-8. The JSON strings
may contain any valid backslash escaping.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
4.4 Status codes and error objects

Every request is acknowledged with a standard HTTP status code, indicating the overall result of the
operation. The codes are used according to the following list.
200 OK - The request was successful.
201 Created - The request has been fulfilled and resulted in a new resource being created.
400 Bad Request - The request cannot be fulfilled due to bad syntax.
401 Unauthorized - The client has either not logged in, has logged in with bad credentials, or the session
has expired.
403 Forbidden - The client has logged in correctly but has not permission to carry out this type of
request.
404 Not Found - The requested resource could not be found.
405 Method Not Allowed - The request was made using a method not supported by that resource.
415 Unsupported Media Type - The request did not have content type of application/json.
In addition to this, an error code (4xx) will be coupled with a JSON object giving details about what
went wrong. A typical client may in some cases present the message property to the operator. A client
developer will find the property developerMessage of use in finding out what happened and what can
be done to avoid this particular situation in the future. The rest of the properties may only be useful for
logging and sending to technical support. This object may contain the following properties, although
some properties can be left out.
status - Integer which is the same as the HTTP status code.
code - Integer identifying the situation in more detail.
resource - URL to the resource involved in the error.
properties - List of properties involved in the error.
message - Short description in the English language suitable to be presented to an operator.
developerMessage - Long technical description suitable to be logged and viewed by a client developer.
4.4.1 Detailed error codes

Below follows a list of error codes that can be returned in the code property of the error object. The first
3 digits of the error code are the same as the HTTP status code of the response.
40001 - The Date header is invalid. Make sure that the Date or X-Aah-Date header is set and has a
valid format.
40002 - Bad request due to invalid content type.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
40003 - Bad request due to invalid message body.

40004 - An unknown property is present in the request object.
40005 - Failed to parse the request.
40006 - A mandatory property is missing in the request object.
40007 - The value of the id property in the body does not match that of the URL.
40008 - Dates and timestamps must be formatted according to ISO 8601.
40009 - Illegal card format specified. It must be rfid48 or TLCode.
40011 - Illegal door operation type specified. It must be guest or normal. In case of Staff card it should
be normal otherwise guest.
40012 - Illegal door category.
40013 - Illegal syntax in serialNumbers property. It must be a list of asciihex-strings.
40014 - Illegal syntax in alarmTypes parameter. It must be a list of integers.
40015 - Cannot change the doors of a card when card holder belongs to user group with uniform access.
40017 - Illegal card ID was found in the list of joiners.
40018 - Property doorOperations must be a list of objects.
40019 - Door list in doorOperations property must be a list of strings.
40020 - Door group list in doorOperations property must be a list of strings.
40021 - Guest room doors cannot be added to a card with joiners.
40022 - A mandatory parameter is missing in the query string of the request.
40023 - Action parameter cannot be used when updating an existing card.
40024 - Multiple commands are not allowed in the same request. Split the request into several requests.
40025 - Commands and property changes are not allowed in the same request. Split the request into
several requests.
40026 - Parameter must be true or false.
40027 - Timestamp must be in UTC and formatted according to ISO 8601.
40028 - Timestamp must be in local time and formatted according to ISO 8601.
40029 - Invalid query parameter value.
40030 - Illegal syntax in the eventType property.
40031 - Invalid Time Schedule. It must be an existing value in Database.
40034 - Only checkout command is allowed for multiple doors. Split the request into several requests
for each door.
40035 - Invalid property value.
40036 - Unknown access ID specified. The access ID is not in the white-list on the server.
40037 - Credential already exists.
40038 - An invalid combination of parameters is used in the query string of the request.
40039 - Illegal syntax in inheritedGroupDoors property. It must be a list of strings.
40040 - Card holder name is not valid.
40041 - Value of ConfirmPin cannot be empty.
40042 - Value of property pin not matched with confirmPin.
40043 - Time must be formatted according to ISO 8601 (i.e. hh:mm:ss).
40044 - The specified operation also required the property.
40045 - Property counters must be a list of objects.
40046 - counterNames list in counter property must be a list of strings.
40048 - Value of Expire time cannot be in the past.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
40049 - Invalid format of metaData property. Property metaData must contain a list of key - value pairs.
40050 - The entered track 2 string is not valid. It either contains invalid characters, or contains too few
or too many replacement characters of the same type in sequence.
40051 - The valid range for the timeout parameter is 1 to 600 seconds.
40052 - Endpoint not found.
40101 - The time skew between the client and the server is too big. Adjust the HTTP header Date or
X-Aah-Date to match the server time.
40102 - A new session could not be created since the client has supplied bad credentials.
40103 - The supplied session ID does not exist. It may have expired.
40104 - The signature of the request did not match calculated signature.
40105 - The Content MD5 Header value does not match the MD5 value of the message body.
40106 - The Authorization header is invalid.”,”The Authorization header is malformed.
40107 - You are not authorized to perform this action on this resource.
40108 - A new session could not be created since the encoder name is not specified in the request.
40301 -
40302 - Refused to overwrite a valid card. You must use overwriteValidCard=true.
40303 - Encoding of card was not possible.
40304 - Refused to overwrite a valid operator card.
40305 - Not authorized to overwrite card.
40307 - Not authorized to create this kind of card.
40308 - Validity of card is longer than allowed.
40310 - Not authorized to perform this function.
40311 - Cannot delete group that has members.
40312 - Guest card overlaps with existing card. You must either specify joiners or use override=true.
40313 - Cannot abort encoder operation.
40314 - Cannot join with cards that are not currently joiners unless they are updated.
40315 - No. of used licenses:
40316 - Internal error.
40317 - Mifare Classic card no longer supported:
40318 - Special rights not yet enabled for the specified accessID.
40319 - Validation Time change is not allowed.
40320 - Change uniform access is not allowed.
40321 - Change time schedule is not allowed.
40323 - New users cannot be added in those user groups which are synchronized from Active Directory.
40324 - User belongs to a user group which is synchronized from Active Directory and request contains
one or more properties which can only be updated from Active Directory.
40325 - Invalid value provided for syncWithActiveDirectory property. Synchronized with Active
Directory setting cannot be removed from fixed staff user group.
40326 - The specified operation is not allowed on this resource. Returning a card image for external
encoding not possible without the proper option enabled.
40327 - The specified operation is not allowed on this resource. It is not possible to add temporary room
access to this resource without the proper option enabled.
40328 - The specified operation is not allowed on this resource. It is not possible to create TLCode
format cards for mobile access without the proper option enabled.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
40401 - The resource does not exist.

40402 - The resource seems to exist, but all parts of it could not be read.
40403 - The specified blocking group does not exist.
40404 - The specified user group does not exist.
40405 - The specified card holder does not exist.
40406 - The specified door does not exist.
40407 - The specified encoder does not exist.
40408 - No guest is currently checked in to room.
40409 - The specified callback does not exist.
40410 - The specified inherited user group does not exist.
40411 - The specified card does not exist.
40501 - The request method is not allowed on this resource.
40503 - The specified operation is not allowed for the door.
40504 - The specified operation is not allowed on this resource. This resource requires a license for a
certain option
40505 - The specified operation is not allowed on this resource. Blocking groups cannot be modified
without the blocking groups option enabled.
40506 - The specified resource is not available in this session. This service device need to be granted
access in order to use extended resources.
40507 - Mobile Access EndPoint ID with length more than 50 characters is not allowed.
40509 - Only one operation can be specified per door.
40510 - The specified operation is not allowed on this resource. Synchronization with Active Directory
not possible without the Active Directory option enabled.
40511 - The specified operation is not allowed in unlicensed mode.
40901 - The resource cannot be created because it already exists.
40902 - There is/are valid staff card(s) for this user. Please provide override=true to cancel all previ-
ous staff card(s).
40903 - List of serialNumbers can not be used in combination with metaData.
40904 - The maximum number of allowed staff cards per user has been reached. An existing card has
to be cancelled before a new can be issued.
41501 - The request did not have content type of application/json; utf-8. Please make sure that content
type is set when json data is passed to the message body.
41502 - Parameters cardID and credentialID cannot be used together. Either provide cardID or
credentialID.
50001 - Internal server error.
50002 - Failed to parse JSON object in AppWebService.
50003 - Failed to parse JSON object received from AppWebService.
50004 - Missing method in command received by AppWebService.
50005 - Unknown method in command received by AppWebService.
50006 - Missing resource in command received by AppWebService.
50007 - Unknown resource in command received by AppWebService.
50008 - Missing object in command received by AppWebService.
50009 - AppWebService forgot to assign value to status or objectType variables.
50010 - Unexpected database response.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
50011 - The requested functionality has not been implemented.

50012 - Unable to generate a callback ID.
50016 - Unhandled httpsend response.
50017 - Failed to read from AppWebService socket.
50018 - Failed to write to AppWebService socket.
50019 - Failed to create a temporary guest user.
50201 - Bad gateway.
50202 - Active directory settings are not configured correctly.
50203 - Operator could not be authenticated through Active Directory.
50204 - Operator could not be logged-in. It is the only available system manager in Visionline but it’s
operator template has been modified in Active Directory.
50205 - Operator could not be logged-in. Invalid user group defined in Active Directory for this user.
50206 - Operator could not be logged-in. Invalid operator template defined in Active Directory for this
operator.
50207 - Operator could not be logged-in. Either user does not exist in the configured OU or user’s
operator template/user group details are missing in Active Directory.
50208 - Operator could not be logged-in. Some error happened while fetching details of this operator
from Active Directory. Check event logs for more details.
50209 - Mandatory fields missing in the AD field mappings configuration.
50301 - Service is unavailable.
50302 - Operation was aborted.
50303 - Service is unavailable. Max number of threads reached.
50401 - Gateway timeout.
50402 - No card on encoder.
50403 - Card sector read error.
50404 - No response from encoder.
4.5 Request signatures

This section may be easier to grasp by studying and running the reference implementation in section 6
and by reproducing the use cases 7.1.1, 7.1.3 and 7.1.4
Each request made to a resource other than those required for creating a session must be signed with the
session access key. The signature is passed in the HTTP header field Authorization and has the form
AWS sessionId:signature. Failure to provide a correct signature in the Authorization header field
will result in 401 Unauthorized, as described in section 4.4.
The first step when signing a request is compiling the string that should be signed. This string is built up
from the following six elements:
1. HTTP verb
2. Content-MD5 header
3. Content-Type header
4. Date
5. Canonicalized headers
6. Canonicalized resource

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
The resulting string, encoded as UTF-8, is signed using HMAC-SHA1 with the session access key [5, 6].
The signature, encoded as Base64, is sent as the HTTP header Authorization on the form AWS sessionId:
signature (note the space between AWS and session ID, but no spaces around the colon).
When the server receives the request, it will pick up its local copy of the access key associated with
the session ID supplied by the client and generate the signature using the method described here. If
this signature matches the one in the Authorization header, the server will process the request. If the
server has no key associated with the session ID, it will return error code 40103. If the signatures don’t
match, it will return error code 40104.
4.5.1 HTTP verb

This is the HTTP method name, GET, POST, PUT, etc., followed by a line feed character.
4.5.2 Content-MD5 header

This is the value of the Content-MD5 HTTP header field, which is the MD5 digest of the request body
encoded as Base64. It is terminated by a line feed character. If the request has no Content-MD5 header,
this part will contain only the line feed character.
4.5.3 Content-Type header

This is the value of the Content-Type HTTP header field, which will be application/json charset=
utf-8 in a POST or PUT request. It is terminated by a line feed character. If the request has no
Content-Type header (in e.g. a GET request), this part should contain only the line feed character.
4.5.4 Date
This is the value of the Date HTTP header field, which is the date and time when the request was sent,
according to the client. It is terminated by a line feed character. The client must synchronize its time to
the server, as described in section 4.5.7. If the header X-Aah-Date is present, this part should be empty
except for the line feed character.
4.5.5 Canonicalized headers

If the HTTP header X-Aah-Date is present, it should be included after it has been converted using the
following method:
1. Convert the HTTP header name to lower-case.

2. Trim any white-space around the colon following the header name.
3. Append a line feed character after the header value.
If there is no HTTP header X-Aah-Date, this part should be empty.
4.5.6 Canonicalized resource

This part starts with the path part of the URL, without decoding percent-encoded characters, up until but
not including the query string. If the URL has a query string, the ? is preserved at the beginning. The rest
is divided at the & signs. These parts are sorted lexicographically and put back together again to form a
canonicalized version of the same query string. This string is not terminated by a line feed character.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
4.5.7 Client and server time in requests

The timestamp of the request need to be within 15 minutes of the server time when the request is received,
or the server returns error 40101. Since this timestamp is included in the string that the client signs with
the access key, it prevents requests that are older than 15 minutes from being replayed to the server.
When the client receives the error 40101, it can read the server’s time in the HTTP header Date of the
response. The client then needs to adjust the time it sends in its own Date header in order to convince the
server that the request is valid. If the client software cannot control the value of the Date header, it can
instead use the header X-Aah-Date with the same format. The X-Aah-Date always takes precedence
over Date.
4.6 Session life-time

It is the web server (Apache Tomcat) that limits the maximum life-time of a session. The default config-
uration is set to 30 minutes. If a request is sent after a session has expired, the request will not be carried
out and the status code 40103 (see section 4.4) will be returned. The client will need to create a new
session and then re-send the last request.
4.7 Future expansions

The protocol may receive updates in the form of new properties in either requests or responses of a
resource. A client must not fail if it encounters unexpected properties in a response. Any new properties
and query parameters introduced for a resource will not be mandatory, but will instead include reasonable
default values, so the client can ignore the new features if desired.
If a property changes meaning or format in a way that would break the previously documented func-
tionality, the base URL of the protocol will change from /api/v1 to /api/v2. This allows unmodified
clients to continue using the old functionality.
4.8 Performance
It is recommended to keep the HTTPS connection alive between requests in order to speed up the pro-
cessing of subsequent requests.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5 RESOURCES
This section explains all the methods, properties and query parameters for all the resources exposed
through this API. The resources are listed in alphabetical order.
All access to resources usually starts with the creation of a session resource (5.24). However, if an opera-
tor card is required to create a session, a list of encoders can be retrieved without using an Authorization
header, by reading the encoders resource (5.14.1).
Once a session has been established, start by reading about the resource that is the most integral part of
the required function. From there, other resources will be referred to in the text. The list below may
serve as a starting point.
/alarms - Monitor alarms (5.3)
/cards - Issue and validate cards (5.9)
/doors - Send commands to doors and read door information (5.13)
/nodes - Monitor network nodes (5.18)
5.1 /alarmTypes
5.1.1 Methods
GET - Read a list of all alarm types. Returns a list of objects containing id and name.
5.2 /alarmTypes/{id}
5.2.1 Methods
GET - Read information about an alarm type.
5.2.2 Properties
id - Unique ID of this alarm type.
name - Short description of the alarm type.
5.3 /alarms
Requires the option Web service for checking and confirming alarms.
5.3.1 Methods
GET - Search for alarms that have been triggered or completed by the system, or receive notification
when a new alarm of a certain type occurs. Returns a list of objects where the id property refers to
an alarm resource and the updateTime indicates the exact instance when the alarm was updated
(see section 5.4).

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.3.2 Query parameters

alarmType - The type of alarms that should be returned in the list, formatted as a comma-separated list
of alarm types. For information about alarm types, see section 5.1.
updatedSince - Only return alarms that were triggered or completed after this date and time. For con-
tinuous watching of alarms, in order to prevent receiving the same alarm twice, use the highest
value of the updateTime property from the last search response. The time must be represented in
UTC, in order to avoid glitches when the server changes to or from DST.
timeout - If no alarms match the search query, wait this number of seconds for new alarms to be updated.
If omitted or zero, the result is returned immediately, even if the list is empty.
5.4 /alarms/{id}
5.4.1 Methods
GET - Read information about an alarm.
POST - Mark an alarm as completed, by setting the completed property to true.
5.4.2 Properties
id - Unique ID of this alarm.
alarmType - The ID of an alarmTypes resource indicating the type of alarm (see section 5.1).
alarmText - Textual description of the alarm.
alarmTime - The date and time of when the alarm occurred.
card - The card that caused the alarm, or null if the alarm wasn’t caused by a card.
cardHolder - The holder of the card that caused the alarm.
door - The door that caused the alarm, or null if the alarm wasn’t caused by a door.
completed - Boolean that indicates if the alarm has been completed.
completionTime - The date and time of when the alarm was completed, or null if the alarm is hasn’t
been completed.
completionUser - The user that completed the alarm, or null if the alarm is hasn’t been completed.
updateTime - The date and time of when the alarm was updated by the server, in UTC.
5.5 /blockingGroups
5.5.1 Methods
GET - Read a list of all blocking groups. Returns a list of objects where the id contains the name of the
blocking group. From web api version 1.28.0.10 and above blocking group list will contain the
blockingGroupID along with the block group IDs. Earlier version of web api were returning the
Id not the blockingGroupID.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59

includeInternal - Set to true to include the internal groups (that are normally hidden) in the response.
includeDeleted - Set to true to include the deleted groups (that are normally hidden) in the response.
5.5.3 /Example
GET /api/v1/blockingGroups
200 OK
[
{
"id": "Guest",
"blockingGroupID": "’1"
},
{
"id": "Staff",
"blockingGroupID": "2"
}
]
5.6 /blockingGroups/{id}
5.6.1 Methods
GET - Read all properties of a blocking group.
PUT - Create a new blocking group. This requires that the Blocking groups option has been enabled.
POST - Change the id of the blocking group. This requires that the Blocking groups option has been
enabled.
5.6.2 Properties
id - Name of the resource used when referring to the blocking group from other resources.
5.7 /callback
Requires the option Web service for callback.
It is possible to set-up callbacks for specific resources and receive callbacks when those resources are
changed in the system.
5.7.1 Methods
POST - Sets the properties for a new callback.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.7.2 Properties
resources - an object that contains the resources that should be included in the callback.
events - resource the handles events in the system.
emiEvents - resource the handles EMI events in the system.
cards - resource that handles cards in the system.
fields - an array of field names that should be included in the callback.
eventCode - an array of event codes that should be included in the callback (events only).
doors - resource that handles doors in the system, can also be used as an array of doors that should be
included in the callback (for cards and doors only).
notifications - an array of notifications that may contain json objects with further instructions.
users - resource that handles users in the system.
5.8 /callback/{id}
Requires the option Web service for callback.
5.8.1 Methods
GET - Returns the queue of changes for the specified callback.
DELETE - Removes the specified callback.
5.8.2 Query parameters for GET

timeout - The default poll timeout is 4 minutes but the timeout can be specified in seconds if a different
timeout is desired (max 600 seconds).
5.8.3 Properties
id - Unique identifier of a previously set-up callback.
resources - an object that contains the resources queued up for the callback.
events - object that contains the queued up events.
emiEvents - object that contains the queued up events.
cards - object that contains the queued up cards.
doors - object that contains the queued up door changes.
notifications - object that contains the queued up notifications.
users - object that contains the queued up users.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.9 /cards
Requires the option Web service for cards.
5.9.1 Methods
GET - Search for cards by specifying a search criterion using the query parameters listed in sec-
tion 5.9.3. This is used for guest and staff card holder.
The response has the form of a list of objects where the id property refers to a card resource (see
section 5.10.2). If no cards match the search criterion, an empty list is returned.
POST - Create a new card or read a card from an encoder for guest card.
The minimal set of properties that need to be specified are format, expireTime, and doorOpera-
tions. If successful, the server creates a new card resource and assigns an id to it. The contents of
the new resource is included in the response.
It is also possible to create a card by only specifying format and cardHolder. This requires that
the card holder belongs to a user group which has uniform access enabled (see section 5.27.3) and
that the card holder has extendedExpireTime set (see section 5.28.3).
Encode card on encoder - Set query parameter action=encode.

Encode loyalty card - Include the serialNumbers property in the body. The card with a match-
ing serial number will be encoded at an auto-update encoder or at an online door that have
received the card image.
Read card on encoder - Set query parameter action=readCard.
5.9.2 Properties
See section 5.10.2

validTime - Matches cards where this time occurs between startTime and expireTime.
startTime - Matches cards that expire after this time. Must be used in conjunction with expireTime.
expireTime - Matches cards that become valid before this time. Must be used in conjunction with
startTime.
cardHolder - Matches cards where cardHolder is equal to this value.
guestDoor - Matches cards that has this door listed in its doorOperations list, under operation guest.
guestDoor is specified with doorID or doorName.
excludeImplicitDoors - If this parameter is set to true, the implicit door list will be excluded. If omitted
or set to false (default), the implicit door list will be shown in the doorOperations property of the
response.
cancelTimeSince - Matches cards that have been cancelled after this time.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
serialNumber - Matches cards where serialNumber is equal to this value.
pendingImage - If set to true, returns the created images that has not yet been encoded (i.e. status is
not issued).
authenticationKey - This paramater can only be combined with pendingImage true and valid value
of cardType parameter. If set to true, returns the authentication key for the given cardType.
cardType - If cardType is set to DESFire, Classic or Plus, returns the authentication key for given card
type.
Parameters for exactly one time match (either validTime or both of startTime and expireTime), and at
least one of the parameters cardHolder or guestDoor must be specified.
Parameter pendingImage can be used in conjunction with serialNumber or validTime or startTime
and expireTime.
Parameter cancelTimeSince cannot be used in conjunction with any other query parameter according to
the above.
The conditions of all the parameters must be fulfilled for every card that is returned in the response.
5.9.4 Query parameters for POST

action - Set to encode to encode a card, or readCard to read the card on the encoder, or mobileAccess
to create a mobile key.
autoJoin - If set to true, this card will join with any overlapping cards. If set to false or omitted, the
server will return an error if there exists any overlapping cards and the joiners property does not
specify at least one of them. Cannot be used in combination with override.
autoUpdate - If set to true in combination with action being readCard, the card on the encoder will
be updated, if it has any pending modifications stored on the server.
cardHolder - The card will be created for the specified cardHolder name. In case of guest cards, if a
user matching the cardHolder value does not already exist in the database, a new hidden guest user
will be created with the provided cardHolder name and the card will be issued to this user.
encoder - The encoder that shall be used when query parameter action is encode or readCard. Since
the parameters are sent in the URL, any special characters such as whitespace or slash must be
percent-encoded.
loadGroupDoors - If set to true, then the default doors connected to the card holder’s user group will
be loaded and merged with the specified doorOperations.
override - If set to true, this card may override any overlapping cards that are not specified as joiners.
If set to false or omitted, the server will return an error if overlapping cards exist. Cannot be used
in combination with autoJoin.
overwriteValidCard - If set to true, the encoder may write to a card even if it already contains valid
access data. If set to false or omitted, the server will return error code 40302 if an already valid
card is found on the encoder.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
returnCredential - If set to true, the server will return the mobile access credential instead of sending
it directly to the server pointed to by the accountName. If set to false or omitted, the parameter
will be ignored. Can only be combined with action=mobileAccess.
sendJoinersOnline - If set to false, any modifications that are carried out by the server as a result of
updateJoiners being set to true will not be sent to the locks. Instead, they will only reach phys-
ical cards through an encoder performing auto-update. If set to true or omitted, the modifications
will be sent to any guest room doors related to the modifications.
sendOnline - If set to false, the server will not send this modification to any locks. Instead, it will only
reach a physical card through an encoder performing auto-update. If set to true or omitted, the
modification will be sent to any guest room doors related to the modification, unless it was written
directly to a card through an encoder in the same request.
updateJoiners - If set to true, the server will allow adding doors to a card with joiners. The card
images of the joiners will be automatically updated so they are not overridden by the modified
card. If set to false or omitted, the server will return an error if the client tries to add doors to a
card with joiners.
waitForStartTime - If set to false, the server will send this modification to related guest room doors
as soon as possible. If set to true or omitted, the modification will be sent to any guest room
doors related to the modification when the start time has passed, unless it was written directly to a
card through an encoder in the same request.
5.10 /cards/{id}
A card resource represents the data that has been encoded or will be encoded to a card in the near future.
For every new card that should be issued, a new card resource need to be created.
Each card resource contains a list of serial numbers of physical cards, which is empty at first. When the
client requests that a specific encoder writes the contents of the card resource to a card, the serial number
of the card at the encoder is stored in this list. The client may also supply serial numbers when creating
or modifying the card resource. In this case, a card with the proper serial number will be encoded
automatically when presented to an auto-update station or at one of its associated guest room doors.
However, while the auto-update station will always have access to the latest card modifications, a door is
required to be online in order to receive information about the cards it shall encode.
5.10.1 Methods
GET - Read all properties of a card.
POST - Modify some of the properties of a card.
5.10.2 Properties
id - Registration number of this card, assigned by the system.
cardHolder - The user that this card has been or will be issued to. This must be a valid resource in
the users collection (see section 5.28). It defaults to the guest user if none is specified when

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
creating the resource. The user may cause expireTime and doorOperations to be implicitly set
(see sections 5.28.3 and 5.27.3). The cardHolder can only be set at creation and can never be
changed afterwards.
created - The date and time of when this resource was created, or when a property last was modified
that affected the information that needed to be encoded on the card.
startTime - The date and time of when the card becomes valid. Defaults to the current time.
expireTime - The date and time of when the card becomes invalid. If cardHolder refers to a user with
extendedExpireTime, it cannot be set longer than this, and it will be automatically increased by
the system (see section 5.28.3).
cancelled - Boolean value telling if the card has been cancelled. Defaults to false and can only be
changed from false to true, never from true to false.
discarded - Boolean value telling if the card has been discarded. Defaults to false and can only be
overridden - Boolean value telling if the card has been overridden. Defaults to false.
overwritten - Boolean value telling if the card has been overwritten. Defaults to false and can only be
notIssued - Boolean value telling if the card is not issued. Defaults to true and can only be changed
from true to false, never from false to true.
expired - Boolean value telling if the card is expired. Defaults to false.
format - Format of the card. It must be one of the strings listed in section 5.10.3 and is mandatory when
creating a card.
joiners - List of cards that this card shall share door access with instead of overriding it, provided that
the cards share at least one door. This property is only included in the response to a request if the
fields parameter is set to joiners.
doorOperations - List of objects specifying which doors the card has access to. Each object in the list
has the following properties:
operation - Door operation for the doors in this object. It must be set to guest for guest rooms
and normal for doors to common rooms.
doors - List of doors that should be opened with the specified operation. The first door in the list
of the first object with operation guest has the special role of being the main door of the
card. Doors are specified with doorID or doorName.
doorGroups - List of door groups that should be opened with the specified operation. Use the
doors resource (see section 5.13) to find out which doors belong to a specific door group.
numberOfIssuedCards - Integer specifying how many cards that has been issued based on this re-
source. Starts at zero and is automatically incremented by the system.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
serialNumbers - List of serial numbers of all issued cards based on this resource. Serial numbers are
automatically appended to the list by the system when cards are written to by an encoder. If the
cards are of a type without serial number, a value “0” is appended for each card. If serial numbers
are supplied by the client, a card can be encoded at the guest doors of this card or at an auto-update
station.
sectors - List of object describing the raw sector data of a card when query parameter action is
readCard. Each object in the request must contain the properties index, key and keyType, and
the response will contain index and contents. The following properties are defined for each item
of the list.
index - Integer identifying the sector of the card. The first sector has index 0.
key - Hexadecimal 12-character string specifying the 6-byte key that is required in order to read
the contents of the sector.
keyType - Type of the key, either A or B.
contents - Hexadecimal string holding the full contents of the sector. The size of the sector is
given by the length of of the string.
pendingAutoUpdate - Boolean value telling if the card has any pending modifications that will be
written to the card either at a lock that has received the modification or at an encoder performing
auto-update.
timeSchedule - Assign a Time schedule to the card so that the user can be granted access at certain
days and between certain hours. The time schedule has to be exists in the Database otherwise web
service will throw an exception.
metaData - Connect metadata to the card. This property holds a json list of key – value pairs. Each
value entry can contain a json object in itself.
inheritedGroupDoors - List of user groups. The default doors for each user group will be loaded and
merged with the specified doorOperations. This property is only valid in a POST request.
track2 - Track 2 string. Requires the option Track 2 (POS). This string can contain data already available
in Visionline. See Installation Instruction Track 2 Option [9] regarding details. The track 2 string
is transferred to the card upon card encoding.
Note: If the list of serial numbers contains more than one entry, serialNumbers property cannot be used
in combination with metaData property when posting a request.
5.10.3 Card formats

The valid values of the format property are rfid48 and TLCode only.
5.10.4 Encoding and reading card on encoder

Instead of supplying a serialNumber, the client can encode the card directly by specifying an encoder.
A card on an encoder can also be read directly. When reading a card, the request body will be empty,
and the response will contain a full card resource. If the card on the encoder has not been encoded by
this system, all properties of the card resources are left out, except the serialNumbers property. Reading
a serial number from a card does not guarantee that the card can be used by the system, only that it is a
card with serial number.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.11 /counters
5.11.1 Methods
GET - Reads a list of all the stored counters in the database.
5.11.2 Properties
counterName - Name of the counter.
defaultCount - The default counter value.
description - A textual description of the counter.
doors - The doors connected to the counter.
maxCount - The maximum counter value.
timeSchedule - The name of the connected time schedule (if applicable).
resetTime - The time of day when the counter resets.
5.12 /doors
5.12.1 Methods
GET - Return a list of doors in the database.
or
GET - Search for doors by specifying a search criterion using the query parameters listed in sec-
tion 5.12.2.

doorGroup - Return only doors that belong to this door group.
details - If set to true, returns a list of all doors with details.
5.13 /doors/{id}
5.13.1 Methods
GET - Read all normal properties of a door (see section 5.13.2)
POST - Send a command to a door, by specifying exactly one of the command properties (see sec-
tion 5.13.4) and query parameters (see section 5.13.5).

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.13.2 Normal properties

id - Number or name of the door. This value is of string type, even if guest room doors often are
numerical by nature.
allowOnOff - Boolean value for allowing on/off opening of the room.
autoLock - Boolean value that tells if the lock should enter locked state when the door frame switch is
closed.
doorCategory - The conceptual type of door (guest, entrance, elevator reader, etc...).
doorGroup - Name of the door group that this door belongs to. Each door belongs to exactly one door
group.
doorGroupID - The number of the door group.
doorID - The number of the door.
doorName - The name of the door.
doorType - The type of lock hardware.
escapeReturnMode - The manual locking mode.
exitButton - Exit button mode.
exitButtonOpenTime - Exit button open time.
externalRelayMode - Boolean value that tells if internal or external relays should be used.
localName - The name of the door adjusted for string-sorting.
online - Boolean value that tells if the door is online.
openTime - The open time (in seconds) of the door.
profiles - This is an optional object that can contain multiple profiles connected to the specified door.
roomIntervalStart - The start value of the entrance interval.
roomIntervalStop - The end value of the entrance interval.
temporaryAccess - This is an optional object that can contain multiple objects with cards that should be
granted temporary access during a limited time. These card objects consists of registrationNumber,
serialNumber and expireTime.
5.13.3 Door states

A door can be placed in one of the 4 states below, using remote commands, function cards or service
tools.
Normal - The door can be opened with a valid keycard or with a remote open command, but is otherwise
locked.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
Passage - The door is unlocked some periods of the day (or all day) according to a passage time sched-
ule.
Stand open - The door is unlocked for a specified time period, ignoring any passage time schedules
during this time.
Emergency open - The door is unlocked unconditionally, ignoring any passage time schedules or if the
stand open time expires.
5.13.4 Command properties

Requires the option Web service for sending open/close commands to doors.
A door resource can also be used to send commands to locks that can be reached by the server, either
through ZigBee or Ethernet. For this purpose, a door has a set of command properties, used for sending
direct commands to the lock. These properties are write-only and only one can be present in each request.
Writing to a command property is done by sending a POST request. The server will immediately try to
reach the specified device and it will not send a response until the command has reached its target, or
when the command has timed out and the server has stopped trying. This means that it may take up to
20 seconds to complete a successful command to ZigBee lock.
The checkedOut property is exceptional, in that it is immediately acknowledged or rejected. The server
will then carry out the command in the background and the client will not know when it has been com-
pleted.
The command properties are listed below.
open - Set to true to send an opening command to the door. The door is locked again automatically after
a certain time. Setting this property to false is not allowed.
revokePassageTime - A door with a passage time schedule will be deactivate passage mode until this
time occurs. The string forever means it will remain inactive until it is modified. null means that
the passage time schedule is reactivated immediately.
standOpenTime - The door will remain open until this time occurs. The string forever means that the
door will be kept open until this property is set to another value. null means that the door is not
kept open by this method.
emergencyOpen - Set to true to put the door in Emergency Open mode, causing it to remain unlocked
regardless of other activities. Set to false to return the door to normal mode.
checkedOut - Set to true to send a check out command to the door. Setting this property to false is not
allowed.
checkoutTime - It is an optional property to send the checkout time together with checkout com-
mand(please refer parameter checkedOut for checkout command). If this property is set, then
checkout command is not sent to the door until specified time has already passed. In case of
mobile keys, the key is not removed from the phone until checkout time has passed.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
doors - This property provides list of doors to be checked out. Checkout command for a single door
can also be sent by mentioning the door in the request header, so this property is not required
in that case. Door is specified with doorID or doorName. List of doors can be used only with
checkedOut command. Refer use case section ’Sending checkout commands’ for different use
cases.
cardID - It is an optional property to checkout an individual key corresponding to given card ID. This
command will not checkout any other valid guest keys (including physical cards or mobile keys).
Value of this property must be provided as the value id returned in response to the request to issue
guest card. It must only be used to checkout guest cards from online rooms as checkout command
will not be sent over to offline rooms and hence cards will continue to work in these rooms. This
property cannot be combined with property credentialID.
credentialID - It is an optional property to checkout and revoke individual mobile key corresponding
to given credential ID. This command will not checkout or revoke any other valid guest keys
(including physical cards or mobile keys). Value of this property must be provided as the value
credentialID returned in response to the request to issue mobile key. It can be used to checkout
guest key from both online as well as offline rooms as it will revoke key from the mobile and
hence guest can’t access the room using mobile key. Key will not be revoked from mobile until
all the rooms accessible to the key has been checked out. This property cannot be combined with
property cardID.

timeout - The number of seconds that the server should try to reach the door when writing to a command
property. If omitted or zero, the server will not be able to send the command to ZigBee doors.
5.14 /encoders
5.14.1 Methods
GET - Read the names of all encoders. Returns a list of objects where the id property contains the
name of the encoder. These value can be used as the encoder property when creating a session
(see section 5.24.2) or with cards resources as the value of the encoder query parameter (see
section 5.9.4). This method can be performed without an Authorization header.
5.15 /encoders/{id}
5.15.1 Methods
POST - Abort an encoder operation.

action - Set to abort in order to abort an ongoing encoding operation.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.16 /mobileaccess
5.16.1 Methods
GET - Reads a list of all credential services accounts stored in the database.
5.17 /mobileaccess/{id}
5.17.1 Methods
GET - Reads the properties for the specified credential services account.
5.17.2 Properties
name - Name of the account.
description - A textual description of the account.
systemID - The system-id of the account.
5.18 /nodes
Requires the option Web service for reading network nodes.
5.18.1 Methods
GET - Read information about all nodes in the network with a single request. Returns a list of objects,
where each object contains the properties listed in section 5.19.2. The nodes are returned in a
depth-first pre-order traversal, starting with the ROOT node, followed by one of its children, then
by one of its grandchildren (if any), etc.
5.19 /nodes/{id}
A node resource represents the network part of a device that is connected to the server, either through
ZigBee or Ethernet. Some nodes, such as the ZigBee End node and the ZigBee Router, may be associated
with a door or a thermostat. In these cases, the associated functionality is identified by the property
function. Other nodes, such as the ZigBee Gateway and the TCP/IP Concentrator, are fully defined
by this resource, since their function is entirely related to the network. These kinds of nodes will have
function set to null.
Nodes without Ethernet connectivity will have the properties macAddress and ipAddress set to null.
Nodes without ZigBee connectivity will have ieeeAddress set to null and panId, networkAddress and
channel set to −1.
5.19.1 Methods
GET - Read all properties of a node.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.19.2 Properties
id - Name of the resource used when referring to the node from other resources. The server has the
id ROOT and all other nodes can be found by inspecting the children property of the ROOT node
or any of its descendants.
children - List of child nodes of this node.
role - String that informs about the logical location of this node within the network. The valid roles are
listed in section 5.19.3.
name - A name that is either automatically assigned by the system, or an arbitrary name assigned by an
operator.
macAddress - MAC address in hexadecimal, separated by colons.
ipAddress - IP address as dotted decimal.
ieeeAddress - IEEE address in hexadecimal, separated by colons.
panId - Integer identifying which PAN the node is on.
networkAddress - Integer identifying the node within its PAN.
channel - Integer representing which ZigBee channel the node is using.
firmwareVersion - String containing firmware version(s) of this node.
numberOfBufferedCommands - Integer telling the number of buffered commands that are waiting to
be sent to this device.
latestReceiveTime - Time of when the latest message was received from the node.
latestLinkQuality - Integer in the range [0,100] representing the link quality reported in the latest mes-
sage received from the node.
latestLinkQualityTime - Time of when the latest link quality value was received.
averageLinkQuality - Integer in the range [0,100] representing a running average of the latest link
quality values reported by the node.
function - Object describing the function of this node, e.g. if it is connected to a door or a thermostat.
The format of the function object is described in section 5.19.4. If this node has no function other
than forwarding network traffic, this property will be null.
5.19.3 Roles
These are the valid values for the role property of a node.
ROOT - The production server
ZGW - ZigBee Gateway
RT - ZigBee Router

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
EN - ZigBee End node
CGW - TCP/IP Concentrator
ELI - Ethernet Lock Interface
RS-485 GW - RS-485 Gateway
5.19.4 Function object

The function property of a node is either an object with the following properties, or the value null.
type - door, thermostat, thermostatController, doorSwitch, motionDetector, minibar or

safe.
id - Unique name or ID of the functional entity, e.g. the room name or motion sensor address.
subtype - If type is doorSwitch, this is one of window, internal, external. Otherwise, it is null.
5.20 /profiles
The profiles resource can be used to query what type of profiles exists in the database.
5.20.1 Methods
GET - Return a list of profiles in the database.

details - If set to true, returns a list of available profiles with details for each profile.
5.20.3 Properties
See section 5.21.3
5.21 /profiles/{id}
5.21.1 Methods
GET - Returns the properties for the specified profile.

type - Since the profile name is not unique, the type need to be specified in order to get the correct
profile. This parameter is required.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.21.3 Properties
id - Name of the profile.
type - The type of profile. Valid types are BLE and LCX.
5.21.4 BLE specific properties

mode - The operation mode of the BLE module.
rssi - An object with rssi values for tap and seamless.
tap - The rssi value used when accessing a door lock in close proximity.
seamless - The rssi value used when accessing a door lock from a longer distance.
5.21.5 LCX specific properties

dischargeThreshold - The touch sensor discharge threshold specified in units where 1 unit is roughly
10.4ns. Default value is 120 units.
5.22 /resources
The resources resource can be used to query what functionality are available via the API. The inte-
grator can then use this information to control what UI-elements to make available in the integrator’s
application.
5.22.1 Methods
GET - Returns a list of objects where the id property refers to a resource available for the current session
(see section 5.23).
5.22.2 Properties
See section 5.23.2

details - If set to true, returns a list of available resources with details for the current session.
5.23 /resources/{id}
5.23.1 Methods
GET - Returns a list of the specified resource’s available parameters and properties.
5.23.2 Properties
id - Name of the resource.
parameters - An array of available query parameters for the resource.
properties - An array of properties available for the resource.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.24 /sessions
5.24.1 Methods
POST - Creates a session for a client, enabling it to access other resources. The client must supply a
username and a password. The default behavior is that systems are configured to require reading
of an operator card as part of the authentication. In these cases, an encoder must also be supplied.
The response will contain an id and an accessKey, which the client uses for signing each request
and supplying it in an HTTP header, according to section 4.5.
Since the sessions resource is needed for obtaining an access key, this is the only resource that can be
accessed without signing the request.
If the password or the card read by the specified encoder does not match the user credentials stored in
the system, the server will return error code 40102.
A client can request extended access by passing accessID and uuid in the request. The result will then
contain a valid webClientID. The accessID must be obtained from the system. The uuid (generated by
the client) is a unique identifier tied to the client. They are unique to a system/client pair and do not vary
from session to session.
The accessID could be configured in the system to bypass the requirement to authenticate with a card.
In that case the encoder property can be omitted from the request.
5.24.2 Properties
id - The ID that should be used together with the signature in the Authorization header.
username - The id of a user that is allowed to log in through the Web API.
password - The password of that user. This is never sent in a response object.
encoder - The encoder where the operator will put the operator card that belongs to the specified user.
How to retrieve the list of encoders is explained in section 5.14.1.
accessID - If an access ID is passed then the access ID will be checked against the stored access IDs in
the system. An access ID will grant extended access.
uuid - This is the unique ID of the client and should be passed along with the accessID property.
accessKey - If the session was created successfully, this key can be used to sign requests being sent to
other resources.
webClientID - If the passed accessID and uuid are valid the returned webClientID should be used as
registration number in the communication layer with the lock.
5.25 /sessions/{id}
5.25.1 Methods
DELETE - Terminate the current session. A session will also be terminated automatically after a period
of inactivity or when another session is created by the same operator.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.26 /timeSchedules
5.26.1 Methods
GET - Reads a list of all time schedules in the database.
5.26.2 Properties
timeSchedule - The name of the time schedule.
description - The description of the time schedule.
5.27 /userGroups/{id}
All users must belong to a user group. The user group can contain a set of doors that can be of use when
creating cards. Groups that have the property uniformAccess set to true will force its set of doors upon
cards linking to that group.
5.27.1 Methods
GET - Read all properties of a user group.
PUT - Create a new user group. If the Blocking groups option is disabled, a blocking group with the
same id is automatically created.
POST - Modify some of the properties of a user group.
5.27.2 Properties
id - Name of the resource used when referring to the user group from other resources.
doorOperations - List of objects specifying doors that can be useful when creating cards. The format
is the same as the doorOperations property listed in section 7.14.3.
uniformAccess - Boolean that specifies that the doors listed in doorOperations are the only doors that
a card holder belonging to this group can have access to (see section 5.27.3 for details).
expireTime - Replaces the expireTime of a card when uniformAccess is true.
blockingGroup - Blocking group that is used to temporarily block access to a group of cards for certain
doors. If the Blocking groups option is disabled, this property must be either omitted or set to the
id of the user group. If the Blocking groups option is enabled, this property is mandatory and must
identify an existing blocking group (see section 5.5).
autoBlockInRentedRoom - With the Auto-blocking option, it is possible to automatically block chosen

user groups (or if applicable, blocking groups) from all rented online rooms. An example is to
autoblock the group Carpenters to avoid renovation in rooms where guests are staying.
defaultReportTime - This is the default time that will be used when setting up reports in User Notifi-
cations.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
ignoreDeadbolt - This option allows the user to enter rooms that are deadbolted.
ignorePrivacy - If this property is true for a user group (e.g. managers), users of that user group can
have access to the door even when the lock is set in privacy.
maxStaffCardsPerUser - Maximum number of cards that can be issued to a user of this group.
syncWithActiveDirectory - Synchronize the user groups with Active Directory.
timeSchedule - user group can be granted access at certain days and between certain hours provided in
the time schedule.
validation - Validation of cards means that to validate cards is that the card holder enters a PIN code
e.g. once a day at a certain validation lock, such as the main entrance. When the card has been
validated, it will be able to access all concerned doors according to the access pattern that is set
up for the user. When the validation time has passed, the card must be validated again in any
auto-update encoder.
validationTime - When the validation time has passed, the card must be validated again.
5.27.3 Doors and user groups

If a user group has the property uniformAccess set to false, then the the doorOperations property is
just a passive list of doors. A client can read the doorOperations from any user groups and add them,
whole or in part, to the doorOperations property when modifying either a card resource or another user
group resource.
However, if a user group has uniformAccess set to true, doorOperations has a more direct meaning.
When creating a card with a cardHolder that has its userGroup pointing to a group with uniform access,
the client may not supply doorOperations. Instead it is taken from the user group.
If doorOperations of a user group resource with uniform access is modified, these changes will propa-
gate to all valid cards belonging to cardHolders within this group. The guest rooms of these cards will
receive auto-update images so that the cards eventually will receive the modified access data.
5.28 /users/{id}
A user supplies information about a person or type of person that can hold a card. Each user must have
a unique id which is assigned by the client upon creation using a PUT request. A user may also have an
extendedExpireTime, which will be used by the system to extend the expireTime of cards belonging
to this user. The complete set of properties is shown below.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.28.1 Methods
GET - Read all properties of a user.
PUT - Create a new user.
POST - Modify some of the properties of a user.
If a user is modified to have a userGroup that has uniform access, this will trigger auto-update of
valid cards associated with the user. Changing the userGroup to one without uniform access will
not trigger any card updates.
Note: If option Import user and operator data from Active Directory is activated in Visionline then
it is not possible to create or delete a user in the user group which is synchronized from Active
Directory. Furthermore, it is also not possible to modify below mentioned properties of the users
who belong to Active Directory synchronized groups. More details on this option can be found in
the Option Instruction Import user and operator data from Active Directory [10] document.
surname, givenname, userGroup, userDetails1, userDetails2, userDetails3, userDetails4, email,
callPhone, autoDelete
5.28.2 Properties
id - Name of the resource used when referring to the user from other resources.
surname - Surname of the user.
givenName - Given name of the user.
userGroup - User group that this user belongs to. It must refer to an existing resource in the user groups
collection (see section 5.27). It is mandatory when creating the resource.
extendedExpireTime - The maximum expireTime for cards that have this user listed as cardHolder.
The system will automatically increase the expireTime of the card until it can finally be set to
extendedExpireTime. It defaults to null when creating the resource (see section 5.28.3).
autoDelete - Boolean value telling the system that this user can be deleted by housekeeping after the
last card referring to it has become invalid. It defaults to true when creating the resource.
userDetails1 - Arbitrary string of information about the user.
cellPhone - cell phone of the user.
defaultReportTime - This is the default time that will be used when setting up reports in User Notifi-
cations.
email - E-mail of the user.
pin - If the user should have access to any keypad units, enter a PIN code for accessing the keypad units.
confirmPin - Duplicate entry same as PIN for confirmation to check that entered pin is correct.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5.28.3 Extended expire time

Requires the option Auto-extension of guest cards.
The expireTime of a card is typically limited to one year into the future. If a user has the extendedEx-
pireTime property set, the system will periodically increase expireTime for cards where this user is set
as cardHolder, until it finally reaches extendedExpireTime. The new expireTime will reach the card
through auto-update at the guest room door.
6 REFERENCE IMPLEMENTATION
This section contains the source code of a reference implementation in Python [7] of a client using this
Web API. It has been tested in Python 2.7.3, but should work in any version from 2.5 up to 2.7.x, but not
in Python 3.x.
When the AAHWebService object is created, the caller specifies the URL of web service and the cre-
dentials of the operator. The constructor, init (), stores these in the object for use by the other
methods.
The only public method of the class is send request(), and it is used to send a request of any type.
The parameter body is typically included when method is ’POST’ or ’PUT’ and omitted for ’GET’
and ’DELETE’. The method will call create session() when the client needs to log on, and it will
call send single request() to carry out the actual request. If the server reports that the time skew
between client and server is too large, send request() will apply an offset to the date in the subsequent
requests and try again.
The method create session() creates a new session on the server by sending the credentials that
were earlier supplied to the constructor. If successful, it will store the ID and the access key for use when
signing other requests.
The method send single request() starts by encoding the body parameter as JSON and computing
its MD5 digest, given that the parameter was specified. The signature is then constructed using the
method described in section 4.5 and stored in the Authorization header. The request is sent to the
server and the response is read. The response is assumed to be in JSON format, and if this is not the case,
an exception is raised.
The final part of the implementation contains an example of how to create an instance of the AAHWebService
class and perform some simple requests.
6.1 AAHWebService.py
import base64 , hashlib , hmac , json , httplib , socket , re , email

from time import strptime , mktime , timezone , time , gmtime , strftime , daylight
class AAHWebService ( object ) :
def __init__ ( self , baseUrl , username , password , debug_level = 0 ) :

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
""" Constructor of AAHWebService object """
# Use SSL if baseUrl starts with ’https :// ’.

# Split the rest of baseURL at the first ’/’ into host and basePath .
m=re . match ( ’( https ?)://(.+?)(/.*) ’ , baseUrl )
self . _use_ssl = ( m . group ( 1 ) = = ’https ’ )
self . _host=m . group ( 2 )
self . _basepath=m . group ( 3 )
# Store credentials in an object ready to be sent to the server .

self . _credentials ={’username ’ : username , ’password ’ : password }
self . _debug_level=debug_level # Get text output from HTTPConnection

self . _session ={} # Placeholder for session ID and access key
self . _time_skew =0 # Assume that server and client times match
def send_request ( self , method , url , body=None ) :

""" Send a request to the web service .
Automatically handle session creation and time skew.
"""
# Send the request at most 3 times : The first request may need
# a new time skew , the second request may hit an expired session ,
# the third request is successful or has a permanent error .
for _ in range ( 3 ) :
try :
# If we are already logged in , send the request . Otherwise ,
# create the session and then send the request in the next
# loop iteration .
if ’accessKey ’ in self . _session :
( status , resource , server_time ) = \
self . _send_single_request ( method , url , body )
request_was_sent=True
else :
self . _create_session ( )
request_was_sent=False
# Handle time skew (40101) and expired session (40103).

# If the request was sent and everything went fine , or if any
# other type of error occurred , we leave that to the caller .
if status ==401 and resource [ ’code ’ ] = = 4 0 1 0 1 :
_=strptime ( server_time , ’%a, %d %b %Y %H:%M:%S GMT ’ )
self . _time_skew=mktime ( _)−timezone−time ( ) + daylight ∗3600
elif status ==401 and resource [ ’code ’ ] = = 4 0 1 0 3 :
del self . _session [ ’accessKey ’ ]
elif request_was_sent :
return ( status , resource )
except ( IOError , ValueError ) as e :

# Handle connection refused , nameserver lookup failure ,

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
# sslv3 alert handshake failure or server response that was

# not in JSON format .
# Set a temporary error code and try again .
( status , resource ) = ( 5 0 0 , { ’message ’ : str ( e ) . decode ( ’utf -8 ’ ) } )
if self . _debug_level :
print ’error : %s’%resource [ ’message ’ ]
# If the server still returns an error after 3 attempts , nothing

# else can be done except for returning the error to the caller .
return ( status , resource )
def _create_session ( self ) :

""" Send user credentials and record the ID and the access key."""
self . _send_single_request ( ’POST ’ , ’/ sessions ’ , \
self . _credentials , False )
if status ==20 1:
self . _session=resource # Success ! Store ID and key.
return ( status , resource , server_time )
def _send_single_request ( self , method , url , body , sign=True ) :

""" Send a properly signed request to the web service ."""
url=self . _basepath+url
headers ={}
if body :
# Encode request body as JSON
body=json . dumps ( body )
headers [ ’Content -Type ’ ] = ’application /json; charset =utf -8 ’
# Compute MD5 digest

h=hashlib . new ( ’md5 ’ )
h . update ( body )
headers [ ’Content -MD5 ’ ] = base64 . b64encode ( h . digest ( ) )
# Format the date correctly , after applying the client / server skew
headers [ ’Date ’ ] = email . Utils . formatdate ( time ( ) + self . _time_skew )
if sign and ’id ’ in self . _session :

# Canonicalize the URL
( canonicalized_resource , q , query_string ) = url . partition ( ’?’ )
canonicalized_resource+=q+’&’ . join ( sorted ( query_string . split ( ’&’ ) ) )
# Build the string to be signed

string_to_sign=method+"\n"
if ’Content -MD5 ’ in headers :
string_to_sign+=headers [ ’Content -MD5 ’ ]
string_to_sign+="\n"
if ’Content -Type ’ in headers :
string_to_sign+=headers [ ’Content -Type ’ ]
string_to_sign+="\n"+headers [ ’Date ’ ] + "\n"+canonicalized_resource

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
# Create the signature

h=hmac . new ( self . _session [ ’accessKey ’ ] . encode ( ’utf -8 ’ ) , \
string_to_sign . encode ( ’utf -8 ’ ) , hashlib . sha1 )
headers [ ’Authorization ’ ] = ’AWS %s:%s’\
%(self . _session [ ’id ’ ] , base64 . b64encode ( h . digest ( ) ) )
# Communicate with server

if self . _use_ssl :
conn=httplib . HTTPSConnection ( self . _host )
else :
conn=httplib . HTTPConnection ( self . _host )
conn . set_debuglevel ( self . _debug_level )
conn . request ( method , url , body , headers )
response_obj=conn . getresponse ( )
# Interpret response
server_time=response_obj . getheader ( ’Date ’ )
response_body=response_obj . read ( )
if self . _debug_level :
print " reply body: "+response_body
try :
resource=json . loads ( response_body )
except ValueError as e :
resource ={’message ’ : e . message+"\ nServer response :\n"+response_body }
return ( response_obj . status , resource , server_time )
# Example of how the AAHWebService class can be used

if __name__==" __main__ " :
ws=AAHWebService ( ’https :// dc. example .com :443/ api/v1 ’ , \
’cardAdministrator01 ’ , ’secret ’ , 1 )
( status , resource ) = ws . send_request ( "GET" , "/ users /jdoe" )

print json . dumps ( resource , indent =4 , sort_keys=True )
assert ( status ==200)
( status , resource ) = ws . send_request ( "POST" , "/ users /jdoe" , \

{’givenName ’ : ’Jane ’ } )
print json . dumps ( resource , indent =4 , sort_keys=True )
assert ( status ==200)

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7 USE CASES
7.1 Session management and request signatures

These use cases show how the sessions resource described section 5.24 resource is used and apply the
algorithm outlined in section 4.5.
7.1.1 Create a session

Prerequisites: An operator with permission to use the Web API.
A session is created in order to obtain a session ID and a session access key. The client sends a POST
request with a set of credentials.
POST /api/v1/sessions
{
"username": "cardAdministrator01",
"password": "secret"
}
The server verifies that the credentials are correct. Then it creates a session, assigns an ID and an access key to it,
and returns these in the response.
201 Created
Location: https://dc.example.com/api/v1/sessions/342ba291
{
"id" : "f4762aadcf9b4a198463a709d8298e34",
"accessKey" : "5bc59bb85cb046a6ad69e2f1777d6547"
}
The client can now use the ID and the access key to sign requests, as shown in use cases 7.1.3 and 7.1.4.
7.1.2 Create a session with extended rights

Prerequisites: An operator with permission to use the Web API and an existing web client with status set to Allow
(see [8] for information about web client configuration).
Note: If the web client (combination of accessID and uuid) is configured to Ignore operator card, the encoder can
be excluded from the request even though operator cards are enabled in the system.
A session is created in order to obtain a session ID and a session access key. The client sends a POST request with
a set of credentials.
POST /api/v1/sessions
{
"username" : "cardAdministrator01",
"password" : "secret",
"accessID" : "ocean",
"uuid" : "0b03f946-59c4-4d30-990b-c23c0b0088b9"
}

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
The server verifies that the credentials are correct. Then it creates a session, assigns an ID and an access key to it,
and returns these in the response.
201 Created
Location: https://dc.example.com/api/v1/sessions/342ba291
{
"id" : "716bf8e26c67410b9ea3157a9e48bb45",
"accessKey" : "11569f3f076d4efd9726c5e6b32a1e43",
"webClientID" : 10000
}
The client can now use the ID and the access key to sign requests, as shown in use cases 7.1.3 and 7.1.4.
7.1.3 Sign a request without a body

Prerequisites: Use case 7.1.1.
This use case describes how to sign the following GET request.
GET /api/v1/cards?validTime=20130105T1200&cardHolder=jdoe HTTP/1.1

Date: Wed, 16 Jan 2013 15:23:02 +0000
The header has no Content-MD5 field and no Content-Type field, so the second and third lines of the string that
should be signed will be empty. There is also no X-Aah-Date field, so the canonicalized headers part is omitted.
The parameters validTime and cardHolder are rearranged so they become lexicographically ordered, and the
resulting string is:
GET\n
\n
\n
Wed, 16 Jan 2013 15:23:02 +0000\n
/api/v1/cards?cardHolder=jdoe&validTime=20130105T1200
This string, encoded as UTF-8, has a length of 91 characters. It is signed with the session access key AQID-
BAUGBwg= (which was received in use case 7.1.1) using HMAC-SHA1. The resulting signature in hexadecimal
is 341b5e6ed197d4d4dbb2148e67909e2aeedab68e. Encoded as Base 64 it becomes NBtebtGX1NTbshSOZ5Ce-
Ku7ato4=. This value is placed together with the session ID to form the header Authorization AWS 342b-
a291:NBtebtGX1NTbshSOZ5CeKu7ato4=.
7.1.4 Sign a request with a body

This use case describes how to sign the following PUT request.
PUT /api/v1/users/skierkegaard HTTP/1.1

Date: Wed, 4 Jan 1995 03:23:02 +0500
Content-Type: application/json; charset=utf-8
Content-Length: 93
X-Aah-Date: Wed, 16 Jan 2013 15:23:02 +0000

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
{\n
"surname": "Kierkegaard",\n
"givenName": "Søren",\n
"userGroup": "Guests in suite 102"\n
}
The body in this example contains 88 printable characters and 4 line feed characters, resulting in 92 Unicode
characters. (Note that there are 2 space characters at the beginning of each indented line and that the line breaks in
this example are single line feed characters. Unlike the HTTP header, which always uses both carriage return and
line feed in the line breaks, the line breaks of the body can be of any type.)
When the body is encoded as UTF-8, ø (U+00F8) is encoded as 0xc3 0xb8 so the 92 characters will occupy 93
octets. The MD5 digest of these octets is 943120b729dd663786412ac352cebd13. Encoded as Base64 it becomes
lDEgtyndZjeGQSrDUs69Ew==.
The MD5 digest should be included both as a Content-MD5 field in the header and as the second line of the string
that should be signed. This request has a specified Content-Type field, so this is included on the third line.
The Date of this request does not match the server time, so the client has chosen to include the X-Aah-Date
field. Therefore, the fourth line is empty and the X-Aah-Date header is included in its canonical form before the
resource path.
PUT\n
lDEgtyndZjeGQSrDUs69Ew==\n
application/json; charset=utf-8\n
\n
x-aah-date:Wed, 16 Jan 2013 15:23:02 +0000\n
/api/v1/users/skierkegaard
This string, encoded as UTF-8, has a length of 131 characters. It is signed with the session access key AQID-
BAUGBwg= (which was received in use case 7.1.1) using HMAC-SHA1. The resulting signature in hexadecimal is
73feaef17f9c90ed767010f73d8f707734b431fe. Encoded as Base64 it becomes c/6u8X+ckO12cBD3PY9wdzS0-
Mf4=. This value is placed together with the session ID to form the Authorization field. The Content-MD5
field also need to be added to the header, as shown below.
Content-MD5: lDEgtyndZjeGQSrDUs69Ew==
Authorization: AWS 342ba291:c/6u8X+ckO12cBD3PY9wdzS0Mf4=
7.1.5 Terminate a session

The client may terminate the session instead of relying on the session being removed after a period of inactivity.
DELETE /api/v1/sessions/342ba91
200 OK
7.2 Create and read user information

These use cases show how to create a new user and how to read the information about an existing user.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7.2.1 Create a new user

This section describes how to create a new user. The client sends a PUT request with set of properties for the user
as shown in the below example. For details of each peroperty, please see the section 5.28.
PUT /api/v1/users/user1
{
"autoDelete": false,
"cellPhone": "12345",
"pin":"1224",
"confirmPin":"1224",
"defaultReportTime": "03:00",
"email": "email@email.com",
"givenName": "Name",
"hidden": false,
"surname": "SurName",
"userDetails1": "detail1",
"userGroup": "UserGroup1"
}
The server fills unspecified properties with default values and attempts to create a new user.
If successful, information about the new user will be stored in the database.
The new resource is returned in the response as given below.
2015-09-17T15:19:41 Response:
201 Created
{
"cellPhone": "12345",
"extendedExpireTime": null,
"hidden": false,
"id": "user1",
}
7.2.2 Modify information for existing user

The client instructs the server to update the information of an existing user in the system. The client sends a POST
request with set of properties as shown in below example to update the information of user. For details please see
the section 5.28.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
POST /api/v1/users/user1
{
"id": "user1",
"cellPhone": "9876543",
}
If successful, information will be updated in the database and

the following response will be returned:
2015-09-17T15:20:12 Response:
200 OK
{
"cellPhone": "9876543",
"extendedExpireTime": null,
"hidden": false,
"id": "user1",
}
7.3 Create and read guest cards

These use cases show how anonymous guest cards can be created either directly at an encoder or automatically at
the door.
7.3.1 Encode a new card

Prerequisites: A door named 101 and an encoder named EA1.
The client instructs the server to create a new card resource by specifying guest door 101 but does not specify
a cardHolder. The client also adds the parameter action and encoder, telling the server to encode the card
directly.
POST /api/v1/cards?action=encode&encoder=EA1
{
"expireTime": "20130102T1210",

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
"format": "rfid48",
"doorOperations": [ { "operation": "guest", "doors": ["101"] } ]
}
The server fills unspecified properties with default values and attempts to encode a card. If successful, it obtains
the serial number of the card from the encoder and stores all information about the card in the database. The new
resource is returned in the response.
201 Created
Location: https://dc.example.com/api/v1/cards/135792
{
"id": "135792",
"cardHolder": "guest",
"created": "20121220T1432",
"startTime": "20121220T1400",
"expireTime": "20130102T1300",
"cancelled": false,
"format": "rfid48",
"doorOperations": [ { "operation": "guest", "doors": ["101"],
"doorGroups": [] } ],
"numberOfIssuedCards": 0,
"serialNumbers": [ "01020304050607" ]
}
7.3.2 Encode a new card with track 2 data

Prerequisites: A door named 101 and an encoder named EA1.
The client instructs the server to create a new card resource by specifying guest door 101 and track 2 string RRRRR.
See Installation Instruction Track 2 Option [9] regarding track 2 string data and formatting details. The client also
adds the parameters action, encoder and overwriteValidCard = true, telling the server to encode the card
directly and overwrite any valid access data on the card.
POST /api/v1/cards?action=encode&encoder=EA1&overwriteValidCard=true
{
"doorOperations": [ { "doors": ["101"], "operation": "guest" } ],
"expireTime": "20190301T1115",
"format": "rfid48",
"track2":"RRRRR"
}
the serial number of the card from the encoder, transfers the track2 string to the card and stores all information
about the card in the database. The new resource is returned in the response.
HTTP/1.1 201 Created

...
{
"cancelled": false,
"cardHolder": "Guest",
"created": "20190228T110204",

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
"discarded": false,
"doorOperations": [ { "doorGroups": [],
"doors": ["101"], "operation": "guest" } ],
"expireTime": "20190301T1200",
"format": "rfid48",
"id": "100003",
"pendingAutoUpdate": false,
"serialNumbers": [ "04474c12695e80ff" ],
"startTime": "20190228T110204",
"track2": "RRRRR"
}
If the track 2 data is read from the actual card after encoding via the Visionline client, Tools - Read Track1 and
Track2..., the track2 data will display ”00101” in this case.
7.3.3 Read the contents of an encoded card

Prerequisites: An encoder named EA1 and an encoded card.
The client instructs the server to read the card on the encoder.
POST /api/v1/cards?action=readCard&encoder=EA1
The server reads the card on the specified encoder and returns all information about it to the client, in the same
format as that of a response to a GET request for a card resource.
200 OK
{
"id": "135792",
...
"serialNumbers": [ "01020304050607" ]
}
7.3.4 Read serial number of an empty card

Prerequisites: An encoder named EA1 and an empty card.
The client instructs the server to read the card on the encoder.
The server doesn’t recognize the card as one belonging to this system, and therefore only returns the serial number.
200 OK
{
"serialNumbers": [ "08090a0b0c0d0e" ]
}

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7.3.5 Prepare a card for auto-update

Prerequisites: A door named 101.
The client instructs the server to create a new card resource by specifying guest door 101 but does not specify a
cardHolder. The client knows the serial number of the physical card and includes this in the request.
POST /api/v1/cards
{
"expireTime": "20130102T1210",
"format": "rfid48",
"doorOperations": [ { "operation": "guest", "doors": ["101"] } ],
"serialNumbers": [ "01020304050607" ]
}
The server fills unspecified properties with default values and stores information about the card in the database.
The card can immediately get encoded at an auto-update station. The new resource is returned in the response.
201 Created
{
"id": "135792",
"created": "20121220T1432",
"startTime": "20121220T1400",
"expireTime": "20130102T1300",
"cancelled": false,
"format": "rfid48",
"serialNumbers": [ "01020304050607" ]
}
The server will try to send the card data to the involved guest room doors, but this may not happen immediately
because the door may not be online at the moment.
Note: If startTime has been set in the future, the card data will not be sent to the involved guest room doors until
the start time has passed. To get around this the query parameter waitForStartTime can be set to false to tell the
system to send the future card data to the involved guest room doors right away instead of waiting for the card data
to become valid.
7.3.6 Prepare guest card for third party encoding

The client instructs the server to create a new card resource by specifying guest door 101. The cardHolder is
optional. The client knows the serial number of the physical card and includes this in the request along with the
attribute pendingImage=true.
The authenticationKey and cardType are optional and required only if authentication key needs to be included
in the response.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
POST /api/v1/cards?sendOnline=false&pendingImage=true&authenticationKey=true&cardType=Classic
{
"expireTime": "20130102T1210",
"format": "rfid48",
"serialNumbers": [ "01020304050607" ]
}
The returned encrypted image can be written to the card with the same serial number in a third party encoder.
201 Created
{
"id": "135792",
"created": "20121220T1432",
"startTime": "20121220T1400",
"expireTime": "20130102T1300",
"cancelled": false,
"format": "rfid48",
"encryptedImage" : "7832ccf8327d48c29bb20d41cb36ded8f1bb60b548b22b73",
"authenticationKey" : "7832CCF987887AAABCAABBCCDDEEFF00",
"serialNumbers": [ "01020304050607" ]
}
The server will not try to send the card data to the involved guest room doors.
7.3.7 Prepare joiner cards for third party encoding

The client instructs the server to create a new card resource by specifying guest door 101. The cardHolder is
optional. The client knows the serial numbers of the physical cards and includes this in the request along with the
attribute pendingImage=true. This request will create joiners to an existing card so the attribute autoJoin=true
must be included. The authenticationKey and cardType are optional and required only if authentication key
needs to be included in the response.
POST /api/v1/cards?sendOnline=false&pendingImage=true&autoJoin=true&authenticationKey=true
&cardType=Classic
{
"expireTime": "20130102T1210",
"format": "rfid48",
"serialNumbers": [ "0472806AF12680", "046380FAF52680" ]
}

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
201 Created
{
"id": "135794",
"created": "20121220T1432",
"startTime": "20121220T1400",
"expireTime": "20130102T1300",
"cancelled": false,
"format": "rfid48",
"pendingImages" : [ {
"encryptedImage" : "a9e852837a78d7832365593139b1ed267c80fb5bab9b8203",
"serialNumber" : "0472806AF12680ff"
}, {
"encryptedImage" : "aa01703a1f2662c80cb7aec4558b171f2a6f83771089722a",
"serialNumber" : "046380FAF52680ff"
} ],
"serialNumbers" : [ "046380faf52680" ],
}
7.3.8 Prepare staff card for third party encoding

Prerequisites: Doors named 101,102,103. A common door named SPA
The client instructs the server to create a new card resource by specifying guest door 101, 102, 103 and a common
door SPA. The cardHolder is mandatory. The client knows the serial number of the physical card and includes
this in the request along with the attribute pendingImage=true.
The authenticationKey and cardType are optional and required only if authentication key needs to be included
in the response.
POST /api/v1/cards?pendingImage=true&authenticationKey=true&cardType=DESFire
{
"cardHolder": "sym",
"doorOperations": [
{
"doors": [
"101",
"102",
"103",
"SPA"
],
"operation": "normal"
}
],
"expireTime": "20171027T1200",

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
"format": "TLCode",
"serialNumbers": [
"042A67820A3580FF"
]
}
HTTP/1.1 201 Created

content-length: 723
set-cookie: JSESSIONID=77FC324A54E47AE5B25D863320A70D0A; Path=/api/v1; Secure; HttpOnly
server: Apache-Coyote/1.1
x-version: AppWebService 1.29.0.29 / Servlet 1.25.900.1-build0
date: Fri, 27-Oct-17 11:10:49 +0200
content-type: application/json;charset=utf-8
{
"authenticationKey": "EF1AC97C360ACA211C08EA3CAA901894",
"cancelled": false,
"cardHolder": "Sym",
"created": "20171027T111049",
"discarded": false,
"doorOperations": [
{
"doorGroups": [],
"doors": [
"101",
"102",
"103",
"SPA"
],
}
],
"encryptedImage": "505186a1be9dce80860101001b0064812b4b7d0eb300aabd10017afb70f449d02f33baac9889b8
"expireTime": "20171028T1200",
"format": "TLCode",
"id": "100001",
"serialNumbers": [
"042a67820a3580ff"
],
"startTime": "20171027T111049"
}
7.3.9 Issue a card that is a joiner to another card

Prerequisites: Use case 7.6.1 or 7.6.4.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
Two guest cards that are issued at different times can access the same room if the later card is specified as a joiner
to the first one.
The first card is issued without specifying a joiners field. If the ID of this card is unknown, it can e.g. be found
using the method described in use case 7.9.1.
The client puts the ID of the first card as an item in the joiners list.
POST /api/v1/cards?fields=joiners
{
"expireTime": "20130105T1200",
"format": "rfid48",
"joiners": ["135792"],
}
The server verifies that at least one of the doors in doorOperations are shared between the cards. Since the client
supplied the parameter fields=joiners, the response object will contain the resulting card resource, including
the joiners field.
201 Created
{
"id": "135822",
...
"joiners": ["135792"]
}
The joiners list of the second card includes the ID of the first card. The first card also includes the ID of the second
card in the joiners, which can be investigated with a GET request that includes the parameter fields=joiners.
GET /api/v1/cards/135792?fields=joiners
200 OK
{
"id": "135792",
...
"joiners": ["135822"]
}
7.3.10 Issue a card that overrides another card

The client tries to issue a card that overlaps in time and with the doors of another, already issued, card.
{
"expireTime": "20130102T1210",
"format": "rfid48",
}

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
The server detects this and returns an error
403 Forbidden
{
"code": 40312,
"message": "Guest card overlaps with existing card.",
...
}
The client decides to override this card, rather than issuing a joiner card, and repeats the request but includes the
override parameter. This time, the server carries out the request.
POST /api/v1/cards?action=encode&encoder=EA1&override=true
{
"expireTime": "20130102T1210",
"format": "rfid48",
}
201 Created
{
...
}
Once the new card has been used in a guest room door, the overridden guest card will be denied access to that door.
7.3.11 Prepare a card for auto-update and connect metadata to the card
The client instructs the server to create a new card resource by specifying guest door 101 but does not specify a
cardHolder. The client knows the serial number of the physical card and includes this in the request. metaData
is connected to the card by specifying a list of key - value pairs to the request.
POST /api/v1/cards
{
"expireTime": "20170630T1910",
"format": "rfid48",
"metaData": [ { "key" : "key1",
"value" : { "A" : "123", "B" : "456", "C" : "789" }
},
{ "key" : "key2",
"value" : "DEF" } ],
"serialNumbers": [ "01020304050607" ]
}
The server fills unspecified properties with default values and stores information about the card including the
connected metadata in the database. The card can immediately get encoded at an auto-update station. The new

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
201 Created
{
"cancelled": false,
"created": "20170630T135347",
"discarded": false,
"doorOperations": [ { "doorGroups": [],
"doors": [ "101" ], "operation": "guest" } ],
"expireTime": "20170630T2000",
"format": "rfid48",
"id": "100090",
"metaData": [ { "key": "key1",
"value": { "A": "123", "B": "456", "C": "789" } },
{ "key": "key2",
"value": "DEF" } ],
"pendingAutoUpdate": true,
"serialNumbers": [
"01020304050607"
],
"startTime": "20170630T135347"
}
The server will try to send the card data to the involved guest room doors, but this may not happen immediately
because the door may not be online at the moment. Metadata is only kept in the Visionline database.
7.4 Create guest card advanced

These use cases show how to create guest card advanced.
The following parameters and properties can be used for creation of a guest card advanced.
7.4.1 Parameters
action - The value of this parameter should be encode to create the guest card advanced.
encoder - Set to the encoder on which cards will be encoded.
7.4.2 Properties
startTime - The date and time of when the card becomes valid. Defaults to the current time.
expireTime - The date and time of when the card becomes invalid.
format - The format of the guest card advanced must be TLCode (for details please refer to the section 5.10.3)
Note: This is a mandatory property for creation of guest card advanced.
doorOperations - List of objects specifying which doors the card has access to. Each object in the list has the
following properties:
operation - Door operation for the doors in this object. It must be set to guest for guest rooms and normal for
doors to common rooms. At least one guest door should be provided for guest card advanced.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
doors - List of doors that should be opened with the specified operation. The first door in the list of the first object
with operation guest has the special role of being the main door of the card.
The client instructs the server to create a guest card advanced (e.g specifying door 101.) The client also needs to
provide a value of the format property as TLCode for guest, and add the parameter action as encode.
To create a guest card advanced for a given door and encode the card on the provided encoder, the client needs to
provide the value for operation as guest at least for one door and the value for encoder as name of encoder on
which card will encode.
POST /cards?action=encode&encoder=Enc1&overwriteValidCard=true
{
"doorOperations": [
{
"doors": [
"101"
],
"operation": "guest"
}
],
"expireTime": "20150527T2359",
"format": "TLCode"
}

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
After creation of a card, the response will contain the information on the card as follows:
2015-05-27T09:23:44 Response:
201 Created
{
"cancelled": false,
"created": "20150527T092325",
"discarded": false,
"doorOperations": [
{
"doorGroups": [],
"doors": [
"101"
],
},
{
"doorGroups": [],
"doors": [
...
],
}
],
"expireTime": "20150528T0000",
"format": "TLCode",
"id": "171406",
--
"startTime": "20150527T092330"
}
7.5 Create mobile key

These use cases show how to create a mobile key for a guest or staff user. The key will be sent to the user’s mobile
phone.
The following parameters and properties can be used for creation of mobile key.
7.5.1 Parameters
action - The value of this parameter should be mobileAccess to create the mobile key for a door.
autoJoin - If set to true, this mobile key will join with any overlapping card/key for the same door. Cannot be
used in combination with override (guest only).
override - If set to true, this mobile key will override any overlapping card/mobile key if exists. Cannot be used
in combination with autoJoin (guest only).
returnCredential - If set to true, the credential will be returned instead of being sent directly to the server
pointed to by accountName.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7.5.2 Properties
startTime - The date and time of when the mobile key becomes valid. Defaults to the current time.
expireTime - The date and time of when the mobile key becomes invalid.
format - Format of the card. It can be rfid48 or TLCode (for details please refer to section 5.10.3). Note: This is
a mandatory property for creation of a mobile key.
doorOperations - List of objects specifying to which doors the mobile key has access. Each object in the list has
the following properties:
operation - Door operation for the doors in this object.
doors - List of doors that should be opened with the specified operation. The first door in the list of the first object
with operation guest has the special role of being the main door of the card (guest only).
endPointID - Unique endPointID assigned to the user’s mobile phone.
accountName - Starting from version 1.18.0, multiple credential services accounts can be configured in Visionline
server. So, this property provides the unique name of the credential services account to be used. If one or
more credential services accounts are configured in Visionline then it is mandatory to mark one of them as
default account. If this field is missing from the request then Visionline server will use the default account
for the requested operation.
label - It is an optional property. This field provides “Label” field data for mobile keys. This field may contain
plain text as well as predefined placeholders. The placeholders are surrounded by percentage % sign. Vi-
sionline replaces these placeholders with their actual values before issuing mobile key. The final text will
be truncated to 32 characters. The valid placeholders are:
ROOMNUM - Replaced with main guest room number or name

ROOMLIST - Replaced with comma separated list of guest rooms
ROOMRANGE - Replaced with hyphen separated room range or if some rooms do not fit intoany range
then they are added as comma separated list.
SITENAME - Name of the property
CARDNUM - Credential ID
UUID - BLE UUID
USERID - the value passed in the UI field
description - It is an optional property. This field provides “Description” field data for mobile keys. This field
may contain plain text as well as predefined placeholders. The placeholders are surrounded by percentage
% sign. Visionline replaces these placeholders with their actual values before issuing mobile key. The final
text will be truncated to 32 characters. The valid placeholders are:

UUID - BLE UUID
url - It is an optional property. This field provides “URL” field data for mobile keys. This field may contain plain
text as well as predefined placeholders. The placeholders are surrounded by percentage % sign. Visionline
replaces these placeholders with their actual values before issuing mobile key. The valid placeholders are:


Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
UUID - BLE UUID
7.5.3 Create mobile key with override

Prerequisites: A door named e.g. 101 and an endPointId named e.g. endPointId1.
The client instructs the server to create a new mobile key for the door by specifying door 101. The client also needs
to provide a value of the format property as rfid48 or TLCode, and add the parameter action as mobileAccess.
The server will create the mobile key for a given door and directly send the mobile key to the user’s mobile phone.
The client needs to provide the value for operation as guest and the value for override as true.
POST /cards?action=mobileAccess&override=true
{
"doorOperations": [
{
"doors": [ "101" ],
}
],
"expireTime": "20150522T2359",
"format": "rfid48",
"endPointID":"endPointId1",
"accountName":"AssaAbloyCredentialAccount"
}
The server fills unspecified properties with default values and attempts to create a mobile key for the given door. If
successful, it returns 201 Created and directly sends the mobile key to the user’s mobile phone.
The request contains value of the property ”accountName”, hence mobile key will be sent to the endpoint ”end-
PointId1” using credential account ”AssaAbloyCredentialAccount” configured in Visionline.
If user has configured ”Label” field in Visionline as ”Room %ROOMNUM% at %SITENAME%” and as
this request does not include ”label” property, so Visionline will use configured field and send the ”label” text as
”Room 101 at DreamLand” with mobile keys.
If user has not configured ”Label” field in Visionline and as this request also does not include ”label” property then
Visionline will send the default ”Label” text as ”Room 101”.
If user has configured ”Description” field in Visionline as ”%CARDNUM%;%USERID%” and as this request
does not include ”description” property, so Visionline will use configured field and send the ”Description” text as
”1000177;XAB5413888” with mobile keys.
If user has not configured ”Description” field in Visionline and as this request also does not include ”description”
property then Visionline will send the default ”Description” text as ”1000177”.
After issue of the mobile key, the response will contain the credential Id of the key as follows:
2015-05-29T12:55:58 Response:
201 Created

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
{
"credentialID": 1000177
}
7.5.4 Create mobile key as joiner key

Prerequisites: A door named e.g. 101 and an endPointId named e.g. endPointId1
The client instructs the server to create a new mobile key for the door by specifying door e.g. 101 (existing
overlapping card/mobile key and new mobile key, both should work at the door). The client also needs to provide
a value of the format property as rfid48 or TLCode, and add the parameter action as mobileAccess.
The client also needs to provide a value of the operation as guest. Both the existing card/mobile key and the new
created mobile key should work at the door.
POST /cards?action=mobileAccess&autoJoin=true
{
"doorOperations": [
{
"doors": [ "101" ],
}
],
"expireTime": "20150522T2359",
"format": "rfid48",
"endPointID":"endPointId1"
}
The server fills unspecified properties with default values and attempts to create a mobile key for the given door.
If successful, it returns 201 Created and directly sends the mobile key to the user’s mobile phone. Both existing
card/mobile key and the new created mobile key should work at the door.
The request does not contains property ”accountName”, hence mobile key will be sent to the endpoint ”end-
PointId1” using default credential account configured in Visionline.
If user has configured ”Label” field in Visionline as ”Room %ROOMNUM% at %SITENAME%” and as
this request does not include ”label” property, so Visionline will use configured field and send the ”label” text as
”Room 101 at DreamLand” with mobile keys.
If user has not configured ”Label” field in Visionline and as this request also does not include ”label” property then
Visionline will send the default ”Label” text as ”Room 101”.
If user has configured ”Description” field in Visionline as ”%CARDNUM%;%USERID%” and as this request
does not include ”description” property, so Visionline will use configured field and send the ”Description” text as
”1000177;XAB5413888” with mobile keys.
If user has not configured ”Description” field in Visionline and as this request also does not include ”description”
property then Visionline will send the default ”Description” text as ”1000177”.
2015-05-29T12:55:58 Response:
201 Created
{
}

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7.5.5 Create mobile key with label, description and url meta data
Prerequisites: A door named e.g. 101 and an endPointId named e.g. endPointId1.
The client instructs the server to create a new mobile key for the door by specifying door 101. The client also needs
to provide a value of the format property as rfid48 or TLCode, and add the parameter action as mobileAccess.
The client also provies values of the label property as Room#%ROOMNUM%, description property as Cre-
dential ID#%CARDNUM% and url property as http://www.assa.com/Guest%USERID%/Welcome.
The client needs to provide the value for operation as guest and the value for override as true.
POST /cards?action=mobileAccess&override=true
{
"doorOperations": [
{
"doors": [ "101" ],
}
],
"expireTime": "20150522T2359",
"format": "rfid48",
"endPointID":"endPointId1",
"label":"Room#%ROOMNUM%",
"description":"Credential ID#%CARDNUM%",
"url":"http://www.assa.com/Guest%USERID%/Welcome"
}
successful, it returns 201 Created and directly sends the mobile key to the user’s mobile phone.
The content of the label, description and url fields are processed by Visionline and any placeholders found in
these fields are replaced with actual values. The final text sent with mobile key will be:
Lable: “Room#101”
Description: “Credential ID#11000021”
URL: “http://www.assa.com/Guest123456789/Welcome”
2015-05-29T12:55:58 Response:
201 Created
{
}
7.5.6 Create mobile key for staff

Prerequisites: A door named 101, a card holder named jdoe and an endPointId named endPointId1
The client instructs the server to create a new mobile key for the door by specifying door e.g. 101. The client also
needs to provide a value of the format property as TLCode, and add the parameter action as mobileAccess.
The cardHolder property must also be set.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
The client also needs to provide a value of the operation as normal.
POST /cards?action=mobileAccess
{
"cardHolder": "jdoe",
"doorOperations": [
{
"doors": [ "101" ],
}
],
"expireTime": "20180322T2359",
"format": "TLCode",
}
The server fills unspecified properties with default values and attempts to create a mobile key for the given door.
If successful, it returns 201 Created and directly sends the mobile key to the user’s mobile phone. Both existing
card/mobile key and the new created mobile key should work at the door.
2018-03-21T12:55:58 Response:
201 Created
{
}
Note: due to the limited space available in the phone for a mobile key, the complexity of the doors specified
in the doorOperations list may result in a key bigger than can be hosted by the phone.
7.5.7 Create and return mobile key credential

Prerequisites: A door named 101 and an endPointId named endPointId1
The client instructs the server to create a new mobile key for the door by specifying door e.g. 101. The client also
needs to provide a value of the format property as TLCode, and add the parameter action as mobileAccess. To
return the credential instead of sending it to the specified server the parameter returnCredential must be set to
true.
The server will create the mobile key for a given door and return the credential as a base64 encoded object. This
object will then have to be sent via the REST API provided by Credential Services.
POST /cards?action=mobileAccess&returnCredential=true&override=true
{
"doorOperations": [
{

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
"doors": [ "101" ],
}
],
"expireTime": "20180322T2359",
"format": "rfid48",
}
successful, it returns 201 Created.
After issue of the mobile key, the response will contain the credential as follows:
2018-03-21T12:55:58 Response:
201 Created
{
"credential": "VGhpcyBzaG91bGQgYmUgYSBjcm..."
}
7.6 Create and read staff cards

These use cases show how staff cards can be created either directly at an encoder or automatically at the door.
7.6.1 Encode a new card

Prerequisites: A door named e.g. 101 and an encoder named e.g. EA1.
The client instructs the server to create a new card resource by specifying door e.g 101 and a cardHolder. The
client also needs to provide value of the format property as TLCode (which means that the card is greater than
rfid48). The client also add the parameters action and encoder and tells the server to encode the card directly.
The client can also provide the value for the timeSchedule parameter (optional). The value of operation can be
provided as normal.
7.6.2 Properties
startTime - The date and time of when the card becomes valid. Defaults to the current time and for staff card this
date should not be in the future.
expireTime - The date and time of when the staff card becomes invalid.
format - Format of the card. It must be TLCode for a staff card (for details please refer to section 5.10.3).
Note: This is a mandatory property for creation of a staff card.
doorOperations - List of objects specifying to which doors the card has access to. Each object in the list has the
operation - Door operation for the doors in this object. It must be set to guest for guest rooms, normal for doors
to common rooms and on/off for on/off doors. If any entry has operation value as guest then card will be
treated as Advanced guest card insted of staff card.
doors - List of doors that should be opened with the specified operation.
timeSchedule - Name of time schedule.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
cardHolder - Name of the card holder and it is a mandatory property.

counters - It is an optional property. List of objects specifying the names of counters applicable on card.
{
"expireTime": "20130102T1210",
"format": "TLCode",
"doorOperations": [ { "operation": "normal", "doors": ["101"] } , { "operation": "on/off",
"doors": ["107"] } ],
"timeSchedule":"Card always",
"counters":{"counterNames":["Counter1", "Counter2"]}
}
the serial number of the card from the encoder and stores all information about the card in the database. The new
201 Created
{
"id": "135792",
"created": "20121220T1432",
"startTime": "20121220T1400",
"expireTime": "20130102T1300",
"cancelled": false,
"format": "TLCode",
"counters": [
{
"counterName": "Counter1",
"counterValue": 2,
"decValue": 1,
"doors": [
"103"
],
"initialValue": 2,
"lastUse": "n/a",
"resetTime": "14:50",
"timeSchedule": "AMS Checking"
},
{
"counterName": "Counter2",
"counterValue": 2,
"decValue": 1,
"doors": [
"105",
"106"
],
"initialValue": 2,
"lastUse": "n/a",

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
"resetTime": "09:36",
"timeSchedule": "timeSchedule2"
}
],
"doorOperations": [
{
"operation": "normal",
"doors": ["101","103","105","106"],
"doorGroups": []
},
{
"doorGroups": [],
"doors": ["107"],
"operation": "on/off"
}
],
"serialNumbers": [ "01020304050607" ],
"timeSchedule":"Card always"
}
7.6.3 Read the contents of an encoded staff card

Prerequisites: An encoder named e.g. EA1 and an encoded card.
The client instructs the server to read the staff card on the encoder.
The server reads the card on the specified encoder and returns all information about it to the client, in the same
format as that of a response to a GET request for a card resource.
200 OK
{
"id": "135792",
...
"serialNumbers": [ "01020304050607" ],
}
7.6.4 Prepare a staff card for auto-update

Prerequisites: A door named e.g. 101.
The client instructs the server to create a new card resource by specifying door e.g. 101 and a cardHolder. The
client knows the serial number of the physical card and includes this in the request. This operation can also be
used to change the credential of the existing card if already encoded.
POST /api/v2/cards
{

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
"expireTime": "20130102T1210",
"format": "TLCode",
"doorOperations": [ { "operation": "normal", "doors": ["101"] } ],
"timeSchedule":"Card always",
"serialNumbers": [ "01020304050607" ]
}
The card can immediately get encoded at an auto-update station. The new resource is returned in the response.
201 Created
{
"id": "135792",
"created": "20121220T1432",
"startTime": "20121220T1400",
"expireTime": "20130102T1300",
"cancelled": false,
"format": "TLCode",
"doorOperations": [ { "operation": "normal", "doors": ["101"],
"serialNumbers": [ "01020304050607" ],
}
Note:
1. Staff cards cannot be auto-updated in locks and thus nothing is sent to the locks.
2. There is a setting in Visionline (Limit the number of staff cards allowed per user) to set the maximum number
of Staff cards for a user belonging to particular user group. But through Web API we can create only ONE Staff
card for a user and this is a known issue which will be fixed later.
7.7 Modify cards

These uses cases show different ways of modifying cards after they were created.
7.7.1 Change the doors of an issued card

POST request contains the full list of changed doors that the card should have access to.
POST /api/v1/cards/135792
{
"doorOperations": [ { "operation": "guest", "doors": ["101","150","102"] } ]
}
The server stores the changes and sends back the current contents of the card resource.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
200 OK
{
"id": "135792",
"doorOperations": [ { "operation": "guest", "doors": ["101","102","150"],
...
}
As in use case 7.6.4, the changes will be available at an auto-update station immediately, but it may take some time
until it reaches the guest room doors.
7.7.2 Deactivate a card at a specific time

Prerequisites: Use case 7.6.1, 7.6.4 or 7.8.5.
If an already issued card should no longer have access to any doors after a certain time, the client specifies this by
modifying expireTime with a POST request.
{
"expireTime": "20130116T1717"
}
The server stores the changes and sends back the current contents of the card resource.
200 OK
{
"id": "135792",
"expireTime": "20130116T1800",
...
}
As in use case 7.6.4, the new expire time will not reach the card until it is used at its guest room door, after that
door has been available online.
7.7.3 Extend the access time for a card

Prerequisites: Use case 7.6.1, 7.6.4 or 7.8.5.
If an already issued card should be valid for a longer time than initially set, this is done in exactly the same way as
use case 7.7.2, but with an expireTime that occurs later than the current value.
7.7.4 Cancel a card that was misplaced

Prerequisites: Use case 7.6.1, 7.6.4, 7.8.1 or 7.8.5.
Instead of shortening the expireTime, as shown in use case 7.7.2, a card can be cancelled, by setting the cancelled
property to true.
{
"cancelled": true

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
200 OK
{
"id": "135792",
"cancelled": true,
...
}
The server sends the order to cancel the card to both guest room doors and entrance doors that this card have access
to. Thus, the card will not need to be encoded at a guest room door before it is blocked from accessing the entrance
doors, as is the case in use case 7.7.2.
If the card is never detected, the order to cancel it will remain in the entrance doors and guest room doors until
the expireTime encoded on the card has passed. This places a limit on the number of cards that can be cancelled
at once, a limit which does not exist when the card is restricted using a shorter expireTime leaving the cancelled
property at false.
7.7.5 Update joiners of a card automatically

Prerequisites: 7.3.9
If the client wants to add doors to a card that has joiners, the modified card will override the old joiner cards. It
must then recreate the overridden cards as joiners of the overriding card. This can be performed with a single
request using the updateJoiners query parameter.
From use case cards 135792 and 135822 are joiners for door 101. The client adds door 103 to card 135792 using
the following request.
POST /api/v1/cards/135792?updateJoiners=true
{
"doorOperations": [ { "operation": "guest", "doors": ["101", "103"] } ]
}
The server sends the card image for 135792 to doors 101 and 103. This image overrides card 135822 in door 101.
However, the server also sends a new image for card 135822 to doors 101 and 160, and with this image the cards
are joiners again. The server responds with the modified details of card 135792.
200 OK
{
"id": "135792",
"doorOperations": [ { "operation": "guest", "doors": ["101", "103"],
...
}
7.8 User groups and guest cards

These use cases give example of operations involving creating users and user groups, and using these resources
when creating and modifying cards.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7.8.1 Create a user group without uniform access

Prerequisites: A room named “Pool room” and a blocking group named “Loyal guests”.
A user group named “Loyal guests” is created by the client. By setting uniformAccess to false, the group can be
used for keeping a list of doors or for placing users in a certain blocking group.
PUT /api/v1/userGroups/Loyal%20guests
{
"uniformAccess": false,
"doorOperations": [ { "operation": "normal", "doors": ["Pool room"] } ],
"blockingGroup": "Loyal guests"
}
201 Created
Location: https://dc.example.com/api/v1/userGroups/Loyal%20guests
{
"id": "Loyal guests",
"uniformAccess": false,
"doorOperations": [ { "operation": "normal", "doors": ["Pool room"],
"blockingGroup": "Loyal guests"
}
7.8.2 Issue a card using doors from a user group

The doors of the user group “Loyal guests” are read with a GET request.
GET /api/v1/userGroups/Loyal%20guests
200 OK
{
"doorOperations": [ { "operation": "normal", "doors": ["Pool room"],
...
}
The contents of the property doorOperations can then be appended to the doorOperations of a card that shall
have access to these doors.
POST /api/v1/cards
{
"expireTime": "20130102T1210",
"format": "rfid48",
"doorOperations": [ { "operation": "guest", "doors": ["101"] },
{ "operation": "normal", "doors": ["Pool room"] } ]
}
The server creates the new card resource with some of its doors taken from the user group, but apart from this,
there is no link between the card and the user group. The new resource is returned in the response.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
201 Created
{
"id": "135792",
...
"doorOperations": [ { "operation": "guest", "doors": ["101"], "doorGroups": [] },
{ "operation": "normal", "doors": ["Pool room"],
"doorGroups": [] } ]
}
The conditions at the end of use case 7.6.4 applies here as well.
7.8.3 Create a user group with uniform access

Prerequisites: Doors named 102, 103, 105, 106 and a blocking group named “guests”.
A user group named “Guests in suite 102” is created by the client. By setting uniformAccess to true, any card
issued to a cardHolder belonging to this group will receive doorOperations from here.
PUT /api/v1/userGroups/Guests%20in%20suite%20102
{
"uniformAccess": true,
"doorOperations": [ { "operation": "guest", "doors": ["102","103","105","106"] } ],
"blockingGroup": "guests"
}
201 Created
Location: https://dc.example.com/api/v1/userGroups/Guests%20in%20suite%20102
{
"id": "Guests in suite 102",
"uniformAccess": true,
"doorOperations": [ { "operation": "guest", "doors": ["102","103","105,"106"],
"blockingGroup": "guests"
}
7.8.4 Create a user with extended expire time and uniform access
The client creates a user belonging to a group with uniform access enabled. All card issued to this user will receive
doorOperations from the user group. The user also has extendedExpireTime, which will automatically extend
expireTime of the card when required.
PUT /api/v1/users/jdoe
{
"surname": "Doe",
"givenName": "John",
"userGroup": "Guests in suite 102",
"extendedExpireTime": "20170615T1200"
}

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
201 Created
Location: https://dc.example.com/api/v1/users/jdoe
{
"id": "jdoe",
"surname": "Doe",
"userGroup": "Guests in suite 102",
"extendedExpireTime": "20170615T1200"
}
7.8.5 Issue a card to a user with extended expire time and uniform access
The client issues a card to user JohnDoe, known by his ID as jdoe. Since he belongs to a group with uniform
access, doorOperations may not be specified in the request. Since the user has extendedExpireTime, the client
need not specify expireTime. Instead it will be assigned an appropriate value by the system, never exceeding
extendedExpireTime. In this case, the client supplies the serial number of the card. If this is omitted, the card
must be encoded according to use case 7.6.1.
POST /api/v1/cards
{
"format": "rfid48",
"serialNumbers": ["01020304050607"]
}
The system-assigned values of the properties doorOperations and expireTime are displayed in the response.
201 Created
{
"id": "135792"
"created": "20121220T1432",
"startTime": "20121220T1400",
"expireTime": "20130701T0000",
"doorOperations": [ { "operation": "guest", "doors": ["102","103","105","106"],
...
"serialNumbers": ["01020304050607"]
}
The conditions at the end of use case 7.6.4 applies here as well.
7.8.6 Change the doors for all cards within a user group with uniform access
Prerequisites: Use case 7.8.5 and a room named 108.
The doorOperations property of cards belonging to a user within a group with uniform access cannot be modified
using a POST to the card resource. Instead, the doorOperations of the user group need to be modified.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
POST /api/v1/userGroups/Guests%20in%20suite%20102
{
"doorOperations": [ { "operation": "guest", "doors": ["102","103","108"] } ]
}
200 OK
{
"id": "Guests in suite 102",
"doorOperations": [ { "operation": "guest", "doors": ["102","103","108"],
...
}
All cards with cardHolders belonging to this group will be modified through auto-update, according to the end
conditions of use case 7.6.4.
7.8.7 Change group of a user within a group with uniform access

Prerequisites: Use case 7.8.5 and a user group named “Guests in suite 110” created according to use case 7.8.3.
The client changes the userGroup of a user from one group with uniform access to another group with uniform
access.
POST /api/v1/users/jdoe
{
"userGroup": "Guests in suite 110"
}
200 OK
{
"id": "jdoe",
"surname": "Doe",
"userGroup": "Guests in suite 110"
}
The doors of this user’s card will get updated through auto-update.
7.9 Find cards

This use case shows how to search for cards in the system based on certain properties.
7.9.1 Find the card of a card holder

When modifying card resources directly, the client need to know the id of the card. If the user ID of the cardHolder
is known, the client can find any card issued to this user that are or will be valid at a certain time.
GET /api/v1/cards?validTime=20130105T1200&cardHolder=jdoe

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
The server returns a list of object, regardless of the number of matching items it found. Each object only contains
the id property.
200 OK
[
{
"id": "135792"
}
]
The user is created according to use case 7.8.4 with userGroup set to no room. The card can now be created by
following use case 7.8.5.
The card is connected to the user jdoe, but since group “no room” has no doors, the card cannot access anything.
Later, when the rooms have been determined, the userGroup is changed according to use case 7.8.7 and the card
will get encoded when it is used at its new guest room door.
7.9.2 Get the pending image for a specific serial number

Changed cards resources or loyalty cards where a pending image is waiting can be retrieved by sending a query for
the specific serialNumber. The authenticationKey and cardType are optional and required only if authentication
key needs to be included in the response.
GET /api/v1/cards?serialNumber=045e2469c92480&pendingImage=true&authenticationKey=true
&cardType=Classic
If a pending image exists it will be returned. Otherwise an empty object will be returned.
200 OK
{
"encryptedImage" : "752ff0b369f5cf1c87fbe01e9d805e9994a412d3edc981a4",
"expireTime" : "20170223T1000",
"serialNumber" : "045e2469c92480ff"
}
7.9.3 Get pending images for valid cards

Changed cards resources or loyalty cards where pending images are waiting can be retrieved by sending a query
for cards that are valid within a specific time interval. The authenticationKey and cardType are optional and
required only if authentication key needs to be included in the response.
GET /api/v1/cards?validTime=20170223T0000&pendingImage=true&authenticationKey=true
&cardType=Classic
If pending images exist they will be returned. Otherwise an empty object will be returned.
200 OK
[ {
"encryptedImage" : "cf0c787e538d7f406b9c1359a5f8a8f4f5fa37605267352e",

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
"expireTime" : "20170223T1000",
"serialNumber" : "04752f69c92480ff"
}, {
"authenticationKey" : "7832CCF987887AAABCAABBCCDDEEFFAB",
"expireTime" : "20170223T1000",
} ]
Same request but with startTime and expireTime instead of validTime.
GET /api/v1/cards?startTime=20170222T2000&expireTime=20170223T0800&pendingImage=true&authenticationKe
&cardType=Classic
If pending images exist they will be returned. Otherwise an empty object will be returned.
200 OK
[ {
"encryptedImage" : "cf0c787e538d7f406b9c1359a5f8a8f4f5fa37605267352e",
"expireTime" : "20170223T1000",
"serialNumber" : "04752f69c92480ff"
}, {
"authenticationKey" : "7832CCF987887AAABCAABBCCDDEEFFAB",
"expireTime" : "20170223T1000",
} ]
7.10 Door groups

This use case shows how to find out information about a door group.
7.10.1 Find out which doors that belong to a door group

Prerequisites: Doors 101 and 102 belonging to door group 1st floor
If the name of a door group is known, the client and list the doors belonging to that door group .
GET /api/v1/doors?doorGroup=1st%20floor
If the door group exists, the server returns a list of object. Each object only contains the id property.
200 OK
[
{
"id": "101"
}
{
"id": "102"
}
]

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7.11 Network nodes

These use cases show how to obtain information about the current state of the network.
7.11.1 Request information about all nodes in the network at once

The client sends a request for all nodes and receives a list of objects.
GET /api/v1/nodes
200 OK
[{
"id": "ROOT",
"children": ["00230000","00250000","00210000"],
"ieeeAddress": null,
...
},{
"id": "00230000",
"children": [ "00230055" ],
"ieeeAddress": "12:34:56:78:9a:bc:de:f0",
...
},{
...
}]
7.11.2 Request information about a single node in the network

The client determines the ID of the node of interest. The ID must be either ROOT or an ID returned in the children
list of another node resource. The response to the request is a single object representing the node.
GET /api/v1/nodes/00230000
200 OK
{
"id": "00230000",
"children": [ "00230055" ],
"ieeeAddress": "12:34:56:78:9a:bc:de:f0",
...
}
7.12 Sending commands to doors

These use cases show how commands that result in modifying the behaviour of the door can be sent over the
network.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7.12.1 Unlock a door

The client sends a request containing a single property.
POST /api/v1/doors/101?timeout=30
{
"open": true
}
The server sends the command to the door, and when it has been completed, the server responds. The respons only
contains door name returned in the id property.
200 OK
{
"id": "101"
}
7.12.2 Set stand open

{
"standOpenTime": "20180301T1400"
}
200 OK
{
"id": "101"
}
7.12.3 Clear stand open

{
"standOpenTime": null
}
200 OK
{
"id": "101"
}

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7.13 Sending checkout commands

These use cases show how checkout commands can be sent over the network.
7.13.1 Check out all guests from a door

POST /api/v1/doors/101
{
"checkedOut": true
}
The server immediately responds. The respons only contains door name returned in the id property.
200 OK
{
"id": "101"
}
The guest is checked out from the door as soon as the server is able to communicate with the door. This command
will also revoke any mobile keys that are issued for the given door.
7.13.2 Check out all guests from multiple doors

POST /api/v1/doors
{
"doors": ["101","102"],
"checkedOut": true
}
The server immediately responds. The respons contains an array of id property - door name pairs.
200 OK
[
{
"id": "101"
},
{
"id": "102"
}
]
The guest is checked out from the doors as soon as the server is able to communicate with the doors. This command
will also revoke any mobile keys that are issued for the given doors.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7.13.3 Check out all guests with grace time

{
"checkedOut": true,
"checkoutTime": "20180301T1200"
}
200 OK
{
"id": "101"
}
If the door is online then all the guests are checked out from the doors after expiration of given checkout time. This
command will also revoke any mobile keys that are issued for the given doors after expiration of given checkout
time.
7.13.4 Check out an individual guest card

Prerequisites: A valid guest card with id - 103287 exists for door 101
{
"checkedOut": true,
"cardID" : 103287
}
200 OK
{
"id": "101"
}
If the door is online then guest card with id - 103287 is checked out from the door.
7.13.5 Check out an individual mobile key

Prerequisites: A valid mobile key with credentialID - 1103321 exists for door 101
{
"checkedOut": true,
"credentialID" : 1103321
}

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
200 OK
{
"id": "101"
}
If the door is online then mobile key with credentialID - 1103321 is checked out from the door. If corresponding
mobile key does not have valid access to any room other than room 101, then key will also be revoked from the
mobile.
7.14 Set-up callback

These use cases show how to set-up a callback for events, cards and doors.
Since a callback may include a lot of fields that are not of interest, the required fields can be specified to limit the
number of fields included in the response.
7.14.1 Events
Available fields for events are:
doorID - the room number of the door.

registrationNumber - the card registration number if event was generated by a card.
eventTime - the time when the event occurred.
eventCode - the number of the event.
cardNameID - the type of card that generated the event.
repeatFlags - a flag that will be set if the same event occurred multiple times within the same minute.
This example will filter on the below events:
304 - Alert, Battery level low

912 - The door is opened
916 - The door is left open too long
POST /callback
{
"resources": {
"events": {
"eventCode": [
304,
912,
916
],
"fields": [
"doorID",
"eventCode",
"eventTime"

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
]
}
}
}

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
EventCode EventName
16 Error, Guest card overridden
17 Error, Guest card overridden
18 Error, Card not valid yet
19 Error, Wrong PIN
20 Error, Counter value too low
21 Error, Not valid due to anti pass-back
22 Error, Not valid at this time
23 Error, Card cancelled
24 Error, Card usergroup blocked
25 Error, Wrong PIN
26 Error, Command not valid for this lock
27 Error, Card has expired
32 Error, Card only valid during opening time
33 Error, Door unit dead bolted
36 Error, Not valid due to door not closed
37 Error, Not valid due to open status
38 Error, Not valid due to Privacy status
39 Error, Not valid due to Privacy status
40 Error, Not valid due to Passage Revoked
41 Emergency open is activated
42 Emergency open is deactivated
43 Error, Not valid due to DND status
48 Error, Not valid due to Stand Open status
49 Error, Wrong version in door unit
50 Error, Wrong mask version in door unit
51 Error, Internal
52 Error, Internal
53 Error, Access denied due to battery alarm
54 Error, Alarm is not set
64 Staff card accepted
65 Stand Open set
67 Guest Card accepted
68 Guest Suite Card accepted
69 Guest accepted in common room
70 Future Arrival Card accepted
71 Power Down Card accepted
72 One Time Card accepted
73 Guest accepted in entrance door
74 N-Time Card accepted
75 Opening with a network camera
76 Power open
80 Latest Guest card checked out
81 Block user group(s)
82 Card(s) has been cancelled
83 A readout has been done
84 Privacy set
85 Initiation started
86 Initiation completed
87 Calendar exchanged
88 Privacy cleared

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
89 Stand Open cleared

90 Some user groups were blocked
91 Some user groups were unblocked
92 Parameters read
93 Setting of time started
94 Setting of time completed
95 Download of program started
96 Report, Card type 1
112 Subproduct set to Senercomm
113 Passage is revoked
114 Passage is not revoked
115 Added a card to the local-card list
116 Removed a card from the local-card list
117 Added a card to temporary blocking list
118 Removed a card from temporary blocking list
119 The blocking schedule was set
120 Added a card image to the loyalty-card list
121 Removed a card from the loyalty-card list
122 Added a card UID to the loyalty-card list
128 One or more events may have been lost
129 Ping from the server

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59


Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59

257 Error, Wrong programming on card
258 Error, Card can’t be used in a door unit.
260 Error, Wrong serialnumber on card
261 Error, Wrong system number on card
262 Error, Unknown magnetic card
266 Error, Card not programmed
267 Error, PIN 1 missing in Common data
268 Error, PIN 2 missing in Common data
270 Error, Operator card can’t be used in a door unit
271 Error, License card can’t be used in a door unit
272 Error, Wrong product

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
273 Error, Unknown mode

274 Error, Cannot set mode in this product
288 Error, Card was not inserted correctly
304 Alert, Battery level low
305 Alert, Battery level critically low
306 Alert, IR battery level low
307 Alert, IR battery critical low
320 Error, No access to this room
322 Error, Card has expired
323 Error, Card can only access Common rooms
324 Error, Wrong gender
325 Error, Access at this time not allowed
326 Error, The card’s UID not found in loyalty list
327 Error, Card is blocked due to anti-passback
336 Error, Wrong System-ID
352 User Group(s) blocked
353 User Group(s) unblocked
368 Error, Card is cancelled
369 Error, User group is blocked
370 Error, Card is blocked due to wrong PIN
384 Error, Keypad entry
385 Error, Keypad programming sequence
386 Error, Keypad entry interrupted
387 Error, Illegal keypad parameter
400 Error, Local PIN list full
416 Locked (safe)
417 Unlocked (safe)
418 Service Opened (safe)
419 Decoded (safe)
420 Logon (safe)
421 Logoff (safe)
432 Low Battery (safe)
433 Mechanically Opened (safe)
434 Tamper Activated (safe)
435 Clear Memory (safe)
436 ’SEr’ in display (safe)
437 Service has been performed (safe)
448 Incorrect Guest Code (safe)
449 Five Incorrect Codes (safe)
450 Service Open Error (safe)
451 Incorrect Service Code (safe)
452 Service Countdown (safe)
453 Time-out (safe)
454 Door Time-out (safe)
464 Service Code Changed (safe)
465 Old Date/Time (safe)
466 New Date/Time (safe)
467 Configuration Changed (safe)
468 Cold Start (safe)
469 Auto relock feature activated (safe)
470 Auto relock failed because of timeout (safe)
480 The minibar door is opened
481 The minibar door is closed

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
482 The minibar door is left open too long

512 Error, Communication parity
513 Error, Communication framing
514 Error, Communication recieve timeout
515 Error, Communication transmit timeout
516 Error, Communication auhtority
528 Battery exchanged
529 Battery alarm in lock
530 Battery status in lock changed to Access Denied
531 IR battery - alarm
532 IR battery - status changed to Access Denied
533 Backup battery - low
534 Backup battery - critical low
535 IR battery - exchanged
536 Backup battery - exchanged
544 Performed selftest, OK
560 Error, Performed selftest, failed
576 Door unit reset, nothing changed
577 Door unit started
578 Door unit cold started
592 System-ID exchanged
608 Error, Trying to exchange System-ID
610 Error changing System-ID, Control Unit fail
611 Error changing System-ID, no power to LDC
624 Error, Unknown external test
625 Error, Requested product not initiated
640 Emergency opening, Stand Open set
656 Power-Open opening
672 Mechanical key opening
673 Mechanical key closing
674 Mechanical key opening, battery mode
675 Mechanical key closing, battery mode
688 Local PIN opening
704 Passage start time, Stand Open set
705 Passage open
720 Exit Button opening
721 Exit Wallox opening, Stand Open set
736 Error, No exit button allowed at this time
737 Error, Exit-Wallox not allowed at this time
752 Error, Counter on card cannot be repaired
768 Passage time expired, Stand Open cleared
769 Emergency closing, Stand Open cleared
770 Stand Open time expired, Stand Open cleared
771 Open time expired, closing
772 Passage revoked, closing
773 Exit Wallox closed, Stand Open cleared
774 LDC finally locked
776 Stand Open cleared due to alarm set
777 Passage mode cleared due to alarm set
778 LDC locked before setting of alarm
784 Passage start time but revoked, S.O. set
785 Passage Revoke time expired
786 Passage expired but revoked, S.O. cleared

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59

802 Emergency-unlock opening
803 Emergency-unlock code generated
832 Local PIN time expired, PIN erased
833 Local PIN stored
864 Cancel list full, oldest card erased
865 Cancel list cleanup
882 Local PIN stored
896 Dead Bolt thrown
897 Dead Bolt released
898 MUR (Make Up Room) active
899 MUR (Make Up Room) passive
900 DND (Do Not Disturb) active
901 DND (Do Not Disturb) passive
912 The door is opened
913 The door is closed
914 The door is opened
915 The door is closed
916 The door is left open too long
917 The door is opened from the inside
918 The door is forced open
919 The reader has been removed
920 The reader has been mounted
921 Tamper alarm
922 The battery cover has been mounted
923 Knob in locked position
924 Knob in unlocked position
960 Privacy time expired, Privacy cleared
1024 Time changed to Daylight Saving time
1025 Time changed from Daylight Saving time
1040 Door unit changed to Holiday 1
1045 Door unit changed to normal weekday
1056 Battery level below 6.0 volts

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59

1088 Error, Parameter out of range
1120 Error, Wrong programming on card
1121 Error, Unknown command
1122 Error, Command must be encrypted
1123 Error, Smart Card reading
1128 Error, Command only valid in LDC with alarm
1130 Error, Command only valid in LDC
1132 Error, Command only valid in Wallox E
1136 Error, Status data corrupt
1152 Error, Smart Card writing
1174 Error, Not a Timelox Smart Card
1177 Error, Smart Card reading/writing
1179 Error, Smart Card start up
1184 Error, Mag Card reading
1186 Error, Card reading. No data found on Card
1187 Error, Mag Card reading
1189 Error, Card was not inserted correctly
1200 Error, Smart Card writing
1232 Battery warning level reset to default
1233 Battery critical level reset to default
1234 Battery exchange level reset to default
1235 Tick adjust reset to default
1236 Room no reset to default
1250 Error, MovingLog is corrupt
1254 Error, Memory Card reading
1257 Error, Not a Timelox Memory Card
1258 Error, Memory Card reading
1264 A loyalty card was encoded
1265 A loyalty card was not encoded (obsolete)
1266 Loyalty card clean-up
1267 Error, a loyalty card was not encoded
1280 Error, Wrong protocol version

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
1283 Error, Decryption failed

1285 Error in received data
1286 Error, Transmission failed
1296 Error, can’t unlock CU
1297 Error, can’t set room no. No com. with CU
1298 Error, can’t set room no. No power to LDC
1299 Error, can’t lock CU
1300 Error, can’t release alarmbypass
1301 Error, can’t release prealarm
1302 Error, can’t activate prealarm
1303 Error, can’t set alarm
1304 Error, can’t check alarm status
1305 Error, can’t unset alarm
1312 Error, can’t unlock CU
1320 Error, can’t unlock CU. Retry in 1 min
1329 Error, can’t lock CU
1330 Error, can’t lock CU. Retry in 1 min
1332 Error, can’t lock CU. Retry in 1 sec
1344 Error, can’t lock due to Emergency stand open
1345 Error, can’t lock due to Exit stand open
1360 Intruder alarm has been unset
1361 Intruder alarm has been set
1362 Command for unsetting alarm has been given
1376 Access denied due to alarm is set
1377 Unable to unlock due to alarm is set
1379 Unable to set passage mode due to alarm is set
1392 The door was opened by a network camera
1408 TLTrans header corrupt
1409 Transmit buffer overflow
1536 Alert, Prealarm set off
1584 Reserved
1648 Local code invalid
1649 Emergency-unlock code invalid
1664 Panel Gateway connected successfully
1665 LCX/Panel radio pairing successful
1666 LCX/Panel radio pairing failed
1667 API Gateway authentication finished
1668 Error, API Gateway authentication failed
1669 LCX authenticate finished
1670 Error, LCX authentication failed
1671 Error, Panel Gateway communication failed
1672 Error, LCX communication failed
1952 Error, Internal
1969 Error during battery measurement
2000 Room number sent to the BLE module
2001 SEOS data sent to the BLE module
2002 Dormant mode sent to the BLE module
2003 Admin mode sent to the BLE module
2004 New parameters sent to BLE module
2005 BLE module firmware upgrade success
2006 Error, BLE communication failed
2007 Phone did not acknowledge status
2008 Status not delivered, connection already terminated

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
2009 LCU Status received outside time window

2010 Phone did not acknowledge status
2011 Advertising mode sent to the BLE module
2012 Advertising mode parameters sent to the BLE module
2032 Error, Internal
2048 Thermostat cooling - temperature rising
2049 Thermostat heating - temperature dropping
2050 No motion detected in spite of door activity
2051 HVAC excessive run time
2052 Battery alarm from motion sensor
2053 Battery alarm from thermostat
2054 Temperature sensor failure
2055 Door left open (t-stat)
2056 Motion sensor offline
2057 Thermostat offline
2058 Smoke sensor offline
2059 Lock offline from thermostat
2060 Freeze alarm
2061 Excessive occupancy
2062 Smoke detected
2063 Setback has been overridden for too long
2064 Occupancy status changed to unsold
2065 Occupancy status changed to unoccupied
2066 Occupancy status changed to occupied
2067 Occupancy status changed to unknown
2068 Set-point reached first time
2069 Motion detected from wireless sensor
2071 Status quo
2072 Before setting time
2073 After setting time
2074 Door opened by guest
2075 Door opened by staff
2076 Door opened from the inside
2077 Deadbolt thrown
2078 Deadbolt released
2079 Door closed
2080 Maintenance needed
2096 Forced entry
2097 Cold start
2098 Door switch offline
2099 Battery alarm from door switch
2112 Parameters changed
2113 Entering diagnostic mode
2114 Exiting diagnostic mode
2115 The set-point was changed by the user
2116 External door opened
2117 External door closed
2118 Thermostat reset
2119 Door opened
2120 HVAC turned on. Cooling
2121 HVAC turned on. Heating
2122 HVAC turned off
2123 External door ajar

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
2124 The foyer door was opened

2125 The foyer door was closed
2126 The connecting door was opened
2127 The connecting door was closed
2128 External door opened
2129 External door closed
2130 External door ajar
2131 Internal door opened
2132 Internal door closed
2133 Internal door ajar
2134 Window opened
2135 Window closed
2136 Window ajar
2144 Motion sensor online
2145 Thermostat online
2146 Smoke sensor online
2147 Lock online
2148 Door switch online
2149 Service tool connected
2150 Service tool disconnected
2151 Temp sensor connected
2152 Temp sensor disconnected
2153 Intelligent switch activated
2154 Intelligent switch deactivated
2155 Motion detected from wired input sensor
2156 Motion detected from internal sensor
3000 Sequential Intruder
3001 Offline door - no response to commands
3002 Emergency Open too long
3003 Stand Open too long
3004 Inncom Offline
3005 Wandering Intruder
3006 Watch list Triggered
3007 Housekeeping failed
3010 ZigBee Router Offline
3011 ZigBee Gateway Offline
3012 Forced entry detected
3013 Excessive card usage
3014 Party alert
3015 Guest has checked in
3016 SMS quota exceeded
3017 Bad card reader
3018 Time is off
3019 The safe is LFPG (locked from previous guest)
3020 HotSOS error
3021 Invalid staff-card usage
3022 Too many guest cards issued in the client
3023 Thermostat controller offline
3024 Room unoccupied
3025 Room unsold
3026 Room occupied
3027 PMS connection lost
3028 Discarded card is being used

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
3029 Guest has checked out

3030 Guest still in room after checkout
3031 Hard disk failure
3032 Communication error to loyalty master
3033 Communication error to loyalty slave
3034 No door activity
3035 Schindler connection lost
3036 Backup to file server failed
3037 Network problems (several gateways disconnected)
3038 Reprogrammed lock
3039 Access through external door
3040 File transfer to the SFTP server is failing
3041 Dates for next semester are missing in calendar
3042 Network problems (long ping times)
3043 ZigBee PAN Coordinator Offline
3044 Power-open token has been downloaded
3045 Cold-start token has been downloaded
3046 Maximo error
3047 Lock has stopped pinging
3048 ZigBee node has stopped pinging
3049 Card auto-updated
3050 Data warehouse server has stopped importing data
3051 Cancelled card has been used in door/encoder
3052 Database size is close to the maximum limit
3053 Restricted door opened
3054 Transport key will expire soon
3055 Update all keys as transport key will expire soon
3056 Synchronization from Active Directory failed
3999 First guest entry
4004 A power-down card has been issued
4009 An operator card has been issued
4015 An emergency card has been issued
4016 A stand-open card has been issued
4021 An initiation card has been issued
4025 An operator card has been issued
4028 A grand-master card has been issued
5001 Broadcast results
5002 Summary of issued cards
5003 Your card expires
5004 Auto-Update Your Card
5005 Cards Expire
5006 Room assigned
5007 Events
5008 #Sent text messages
5009 Zigbee Status
5010 Low LQI
5011 Main Statistics
5012 Energy Events
5013 Energy Statistics
5014 Occupancy
5015 Non-autoupdated cards
5016 Safe locked at checkout
5017 First entry for loyalty cards

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
5018 Card access audit

5019 DND Doors
5020 MUR Doors
5021 Card statistics report
10000 Operator logged in
10001 Operator logged out
10002 Added record
10003 Removed record
10004 Updated record
10005 Open
10006 Set stand open
10007 Clear stand open
10008 Block user groups
10009 Unblock user groups
10010 Checkout
10011 Emergency open
10012 Emergency close
10013 Move/extend card
10014 Passage revoke set
10015 Passage revoke cleared
10016 Door set as temporary offline
10017 A power-open token was downloaded to Lock Service
10018 A cold-start token was downloaded to Lock Service
7.14.2 EMI Events

Available fields for EMI events are:
doorID - the room number of the door.

eventCode - the number of the event.
expireTime - the expiration time of the card.
mainGuestRoom - the main guest room of the guest card.
userGroupID - the number of the user group of the card.
suiteRooms - the adjacent rooms available to the guest card.
firstEntry - flag that is set when the first guest of a party enters.
POST /callback
{
"resources": {
"emiEvents": {
"fields": [
"doorID",
"eventCode"
]
}
}
}

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7.14.3 Cards
Available fields for cards are:

status - the status of the card where 0=cancelled, 1=valid, 2=overridden, 3=not issued, 4=expired, 5=overwritten,
6=discarded.
cancelTime - the time when the card was cancelled.
mainGuestRoom - the main guest room is the card is of type ’guest’.
cardNameID - the type of card.
issueTime - the time when the card was made.
startTime - the time when the card gets valid.
expireTime - the time when the card expires.
expireTimeOnline - the time when the card expires (when new time set online).
serialNumber - the serialNumber of the physical RFID card.
cardHolder - The user that this card has been issued to.
surname - Surname of the user.
givenName - Given name of the user.
doorOperations - List of objects specifying which doors the card has access to. Each object in the list has the
operation - Door operation for the doors in this object.
doors - List of doors that should be opened with the specified operation.
POST /callback
{
"resources": {
"cards": {
"fields": [
"expireTime",
"cancelTime",
"mainGuestRoom",
"cardNameID"
]
}
}
}
In order to only receive callbacks for cards that can access specific doors you can include an array of the doors
you’re interested in.
POST /callback
{
"resources": {
"cards": {
"doors": [

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
"101",
"Entrance 1"
]
}
}
}
7.14.4 Doors
see section 5.13.2 for the available fields.
In this example, only doorID, doorName and temporaryAccess properties will be included in the callback response.
POST /callback
{
"resources": {
"doors": {
"fields": [
"doorID",
"doorName",
"temporaryAccess"
]
}
}
}
7.14.5 Notifications
In this example, a callback for firmware upgrade notifications will be set-up.
POST /callback
{
"resources": {
"notifications": {
"types": [
"firmware"
]
}
}
}
7.14.6 Users
In this example, a callback for users of a specific user group will be set-up.
POST /callback
{
"resources": {
"users": {
"userGroup": [
"Staff"
]

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
}
}
}
7.14.7 Multiple resources

You can register for multiple resources in the same request.
POST /callback
{
"resources": {
"events": {
},
"doors": {
},
"cards": {
}
}
}
7.14.8 Response
If the request succeeds then the response will contain the id of the callback.
200 OK
{
"id": "182e5c2a99d54bd3802107d436b67243"
}
7.15 Remove callback

If an existing callback is no longer required, it should be removed to free resources on the server. To remove an
existing callback, the id of the callback should be included in a DELETE request.
DELETE /callback/<id>
7.16 Get callback

Callbacks are handled through long polls. That means the integrator will have to send a GET request on the
callback id.
GET /callback/<id>
If there is something in the callback queue a response will be sent back immediately, else the call will hang for
up-to 4 minutes (callback timeout) before returning a response (which may be empty if nothing reached the queue
in time).
All callback records have an expire time of 12 hours.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
GET /callback/dfe8f9ac22b24bedad4a534f2ed1d69a
200 OK
{
"id": "dfe8f9ac22b24bedad4a534f2ed1d69a",
"resources": {
"cards": [
{
"cancelTime": "",
"cardNameID": 0,
"expireTime": "20151216T1200",
"mainGuestRoom": 101
}
]
}
}
7.17 List available resources

Get a list of the resources available for the current session.
GET /resources
The response will contain the available resources for the current session.
200 OK
[ {
"id" : "cards"
},
{
"id" : "doors"
},
...
]
7.18 List available parameters and properties for the cards resource
Get a list of the query parameters and properties that are available for a specific resource.
GET /resources/cards
The response will contain the properties and parameters associated with the resource.
200 OK
{
"id" : "cards",
"parameters" : [ "guestDoor", "encode", ... ],
"properties" : [ "cardholder", "expireTime", ... ],
}

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
7.19 List available resources with details

Get a list of the available resources including the query parameters and properties.
GET /resources?details=true
The response will contain the properties and parameters associated with the available resources.
200 OK
[ {
"id" : "cards",
"parameters" : [ "guestDoor", "encode", ... ],
"properties" : [ "cardholder", "expireTime", ... ]
},
{
"id" : "doors",
"parameters" : [ "doorGroup", "details" ],
"properties" : [ "id", "doorGroup", ... ]
},
...
]
8 REFERENCES
[1] ASSA ABLOY Global Solutions, Specification PMS Plus Protocol, 61 1100 060-45 (DP-060-45), January
11, 2019
[2] Fielding, R. et al., RFC 2616 Hypertext Transfer Protocol – HTTP/1.1, June 1999.
http://www.ietf.org/rfc/rfc2616.txt
[3] AWS documentation, Signing and Authenticating REST Requests, 2013-01-10.
http://docs.amazonwebservices.com/AmazonS3/latest/dev/RESTAuthentication.html
[4] Berners-Lee, T. et al., RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax, January 2005.
[5] Krawczyk, Bellare & Canetti, RFC 2104 - HMAC: Keyed-Hashing for Message Authentication, February
1997.
[6] Burrows, J. et al., FIPS PUB 180-1 Secure Hash Standard, 1995-04-17.
http://www.itl.nist.gov/fipspubs/fip180-1.htm
[7] Python Software Foundation, Python Programming Language - Official Website, 2013-02-11.
http://www.python.org
[8] ASSA ABLOY Global Solutions, Installation Instruction Web Services Options, 66 5013 102-6
[9] ASSA ABLOY Global Solutions, Installation Instruction Track 2 Option, 66 5013 119-4, January 8, 2019
[10] ASSA ABLOY Global Solutions, Option Instruction Import user and operator data from Active Directory,
66 5013 135-1

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
9 DOCUMENT HISTORY
Rev Date Author Description
0 2014-03-11 MAx Initial version released. Supports issuing and modifying guest cards using re-
sources cards, encoders, users and userGroups, monitoring alarms using re-
sources alarms and alarmTypes, monitoring network nodes using the resource
nodes, and sending opening commands to doors using the resource doors.
1 2014-07-03 MAx Manage blocking groups using the resource blockingGroups, auto-update cards
on encoder, update joiner cards automatically, allow aborting of encoder opera-
tion.
2 2014-12-17 Amarjit Added ’timeSchedules’ resource and create and read operation for staff card.
3 2015-05-22 Amarjit Added section for how to create mobile key through web api.
4 2015-05-29 Amit Added section for how to create mobile key with label, description and url meta
data.
5 2015-06-05 Amit Updated description of mobile key description property.
6 2015-06-23 Amarjit Added ’counters’ resource and updated the section users, userGroups and read
anc create staff card.
7 2015-09-17 Amarjit Added example for how to create a new user and how to update the information
about an existing user.
8 2015-10-13 Magnus Added new sections on callback.
9 2016-01-21 Amit Added ’mobileAccess’ resource and updated section ’Create mobile key for
guest’ to add field ’accountName’ and updated examples to show it’s usage.
10 2016-03-16 Amarjit Remove the ’s’ from usersGroups because in all the requests the actual word do
not contain this ’s’.
11 2016-05-06 Amarjit Updated for checkedOut command in door(s).
12 2016-05-25 Magnus /sessions/{id} was misspelled.
13 2016-05-25 Amit Added new user case section ’Sending checkout commands’ for checkout com-
mands. Also updated description of corresponding properties.
14 2016-05-30 Amit Added properties ’cardID’ and ’credentialID’ for checkout command and added
corresponding user cases ’Checkout an individual guest card’ and ’Checkout an
individual mobile key’ under section ’Sending checkout commands’.
15 2016-07-05 Amit Removed wrong examples from descriptions of mobile key description, label
and url properties.
16 2016-08-23 Magnus Extended resources moved to appendix 1.
17 2016-09-21 Magnus Removed email and uuid from the Sessions section.
18 2016-10-05 Miraz Added a note for a known issue in Web API that currently there is no function-
ality to limit the number of staff cards for a user.
19 2016-11-30 Amarjit SSL terminology has been updated.
20 2016-12-18 Magnus Optional properties accessID and uuid added to the Sessions section.
21 2017-02-08 Magnus Added ’doors’ filter for the card callback resource.
22 2017-02-23 Magnus, Per Query parameters ’cancelTimeSince’, ’serialNumber’ and ’pendingImage’ for
GET added to the ’Cards’ resource.
23 2017-03-21 Per Added info about default expire time for callback records and callback timeout.
24 2017-04-24 Magnus Added use cases for third party encoding.
25 2017-05-03 Amarjit Added serverInfo resource.
26 2017-05-09 Per Added metaData property to cards/id resource.
27 2017-05-16 Amarjit updated information for blockingGroups resource.
28 2017-05-30 Per Added Note to cards properties: list of serialNumbers can not be used in com-
bination with metaData property.
29 2017-06-07 Magnus query parameter added to cards and doors resources. New resources resources
added to replace serverInfo.

Web API
Valid from Revision
DocNo: 61 1100 080 2019-08-19 59
Rev Date Author Description

30 2017-06-20 Magnus query parameters added to blockingGroups resource.
31 2017-06-30 Per Added ’Prepare a card for auto-update and connect metadata to the card’ use case.
32 2017-07-05 Magnus Parameter loadGroupDoors and property inheritedGroupDoors added to the
cards resource.
33 2017-08-11 Amarjit Parameter cardType, authenticationKey and property authenticationKey added to
the cards resource.
34 2017-08-17 Miraz Updated supported values for parameter cardType in the cards resource.
35 2017-09-07 Amarjit Updated supported values for parameter cardType in the cards resource.
36 2017-09-19 Magnus Added doors to the callback resource. Modified the callback examples to include
doors.
37 2017-10-04 Magnus Added a use case for creating a session with extended rights. Callback resource
extended with notifications.
38 2017-10-05 Magnus Corrected a missing comma in the use case for creating a session with extended
rights. Also added a reference to a document about configuring web clients.
39 2017-10-27 Miraz Added section for preparing staff card for third party encoding.
40 2017-10-30 Miraz Updated supported values for parameter cardType in the cards resource for Mifare
Plus cards.
41 2017-11-14 Miraz Added cardHolder property description in cards POST API that a cardHolder will
be created if it doesn’t exists.
42 2017-11-22 Magnus Added a new section about session life-time.
43 2018-02-05 Per Clarified how doors are specified with doorID or doorName in subsections: guest-
Door in Query parameters for GET, doors in Cards-Properties, id in /doors/{id}-
Normal properties and doors in /doors/{id}-Command properties.
44 2018-02-09 Miraz Corrected the authenticationKey value from 9 bytes to 16 bytes in examples.
45 2018-02-12 Magnus Added section for mobileaccess/{id} with new property systemID.
46 2018-03-01 Per Added description of responses to Sending commands to doors and Sending checkout
commands sections.
47 2018-03-21 Magnus Added examples of how to create a mobile staff key.
48 2018-04-06 Stefan Added query parameter excludeImplicitDoors for GET /cards command.
49 2018-04-16 Magnus Dashes removed from the callback id shown in the examples.
50 2018-08-06 Miraz Updated cardHolder property description in cards POST API that a cardHolder will
be created if it doesn’t exists only for guest cards.
51 2018-09-12 Magnus New query parameter waitForStartTime added to the cards resource.
52 2018-09-25 Magnus New resource profiles added.
53 2018-10-03 Magnus New query parameter timeout added to the callback resource.
54 2018-10-11 Magnus New profile type added to the profiles resource.
55 2019-01-11 Filip Added missing events to the Event Code list.
56 2019-02-28 Per Added description for track2 property to cards/{id} resource and an example to the
Use cases section. Changed document title and logo to reflect the change to ASSA
ABLOY Global Solutions.
57 2019-06-20 Magnus New query parameter returnCredential added to the cards resource.
58 2019-08-19 Filip Added users to the callback resource.
59 2019-08-19 Filip Added new card statuses to the card resource to help identify the state of cards.


ASSA ABLOY Global Solutions Web API

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ASSA ABLOY Global Solutions Web API

Uploaded by

Copyright:

Available Formats

Web API

Valid from Revision

/svn/documents/1100 - Utvecklingsavdelningen/61/61 1100 080 - AAH Web API/*.tex

3 Security and authentication 9

5.13.3 Door states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

7.3.9 Issue a card that is a joiner to another card . . . . . . . . . . . . . . . . . . . . . 54

7.10 Door groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

9 Document History 101

HTTP - Hypertext Transfer Protocol, an application protocol for distributed media.

HTTPS - Hypertext Transfer Protocol Secure, HTTP encrypted with SSL.

JSON - JavaScript Object Notation, a text-based standard for data representation.

REST - Representational State Transfer, an architectural style for distributed systems.

3 SECURITY AND AUTHENTICATION

3.1 Encrypted communication channel

3.2 Initial authentication

3.3 Authentication of requests

Collection resources - Entities that represents a collection of basic resources.

In principle, all resources could be accessed using the following actions:

• Read all properties of a resource using a GET request.

• Replace all properties of an existing resource by using a PUT request.

• Modify one or more properties of an existing resource by using a POST request.

• Remove a resource using a DELETE request.

• Some properties of a resource are left out in a GET request.

• Some resources cannot be created through the Web API.

• Some resources cannot be removed by the user.

4.2 URL structure

4.3 Request body

4.3.1 Basic data types

4.3.2 Date and time representation

4.3.3 Character encoding

4.4 Status codes and error objects

200 OK - The request was successful.

404 Not Found - The requested resource could not be found.

status - Integer which is the same as the HTTP status code.

code - Integer identifying the situation in more detail.

resource - URL to the resource involved in the error.

properties - List of properties involved in the error.

message - Short description in the English language suitable to be presented to an operator.

4.4.1 Detailed error codes

40003 - Bad request due to invalid message body.

40401 - The resource does not exist.

50011 - The requested functionality has not been implemented.

4.5 Request signatures

4.5.1 HTTP verb

4.5.2 Content-MD5 header

4.5.3 Content-Type header

4.5.5 Canonicalized headers

1. Convert the HTTP header name to lower-case.

If there is no HTTP header X-Aah-Date, this part should be empty.

4.5.6 Canonicalized resource

4.5.7 Client and server time in requests

4.6 Session life-time

4.7 Future expansions

/alarms - Monitor alarms (5.3)

/cards - Issue and validate cards (5.9)

/doors - Send commands to doors and read door information (5.13)

/nodes - Monitor network nodes (5.18)

name - Short description of the alarm type.

5.3.2 Query parameters

5.5.2 Query parameters

events - resource the handles events in the system.

emiEvents - resource the handles EMI events in the system.

cards - resource that handles cards in the system.