Lock Groups¶
Get List of Lock Groups¶
Get a list of this owner account's lock groups.
Scope¶
read:core:entities
Parameters¶
Tip
The returned list can be filtered using OData query parameters.
Name | Type | Location | Description |
---|---|---|---|
ownerAccountId | string | path | The owner account's ID. |
expand | string | path | Optional. A comma-separated list of expandable properties. |
Response¶
200 OK
[
{
"active": true,
"rclSerialNo": null,
"rclDate": null,
"targetType": "Group",
"id": "1",
"physicalLockId": null,
"title": "Office Building",
"description": "A description for this lock group."
}
]
Expandable properties¶
Supported features¶
When passing supportedFeatures
to the expand query parameter, the response will contain the following additional property:
"supportedFeatures": {
"timeRestrictionIcalSupport": "Supported"
}
Statistics¶
When passing statistics
to the expand query parameter, the response will contain the following additional property,
"statistics": {
"ByState": [
{
"State": "Joined",
"Count": 5
},
{
"State": "UnjoinPending",
"Count": 1
},
{
"State": "Unjoined",
"Count": 1
}
]
}
where State
can be either JoinPending
, Joined
, or UnjoinPending
and Unjoined
. The Count
property lists the number of locking devices in the respective state.
Get Lock Group by ID¶
Get the specified lock group.
Scope¶
read:core:entities
Parameters¶
Name | Type | Location | Description |
---|---|---|---|
ownerAccountId | string | path | The owner account's ID. |
expand | string | path | Optional. A comma-separated list of expandable properties. |
id | string | path | The lock group's ID. |
Response¶
200 OK
{
"active": true,
"rclSerialNo": null,
"rclDate": null,
"targetType": "Group",
"id": "1",
"physicalLockId": null,
"title": "Office Building",
"description": "A description for this lock group."
}
Expandable properties¶
Please see the expandable properties of the
GET/Owners/{ownerAccountId}/LockGroups/
operation above.
Create Lock Group¶
Create a new lock group.
Scope¶
write:core:entities
Parameters¶
Name | Type | Location | Description |
---|---|---|---|
ownerAccountId | string | path | The owner account's ID. |
Body¶
{
"title": "Office Building",
"description": "A description for the new lock group."
}
Response¶
200 OK
{
"active": true,
"rclSerialNo": 1,
"rclDate": null,
"targetType": "Group",
"id": "1",
"physicalLockId": "DAAl1T7twFAiUeZ56tI=",
"title": "Office Building",
"description": "A description for the new lock group."
}
In case the passed data does not contain a title:
400 lock group must have a title
If the provided owner account ID is invalid:
404 owner account not found
Patch Lock Group¶
Patch the specified lock group.
The following properties can be patched:
title
description
Scope¶
write:core:entities
Parameters¶
Name | Type | Location | Description |
---|---|---|---|
ownerAccountId | string | path | The owner account's ID. |
id | string | path | The lock group's ID. |
Body¶
{
"title": "Office Building B",
"description": "A new description for this lock group."
}
Response¶
200 OK
{
"active": true,
"rclSerialNo": 1,
"rclDate": null,
"targetType": "Group",
"id": "1",
"physicalLockId": "DAAl1T7twFAiUeZ56tI=",
"title": "Office Building B",
"description": "A new description for this lock group."
}
Delete Lock Group¶
Delete the specified lock group.
Marks a lock group as deleted, which will remove it from lists intended to be displayed to the user. The lock group will only be marked as deleted, rather than actually removed from the database, because the data might be needed in some cases even after deletion.
If the group has member locks assigned, the behaviour is as follows:
- If
forceUnjoinLocks
is set totrue
, any member locks will start the unjoin process for any active memberships as part of this operation. Note, that syncing the affected lock is still required in order to complete the unjoining process. - If
forceUnjoinLocks
is set tofalse
, the operation will fail if any member lock is in a state other thanUnjoined
. That is, the membership has not been marked as deleted or the lock hasn't been synced thereafter.
If the group has active grants, the behaviour is as follows:
- If
forceRevokeGrants
is set totrue
, the revocation process will be started for the affected grants as part of this operation. - If
forceRevokeGrants
is set tofalse
, this operation will fail, if any active grants are assigned.
Scope¶
write:core:entities
Parameters¶
Name | Type | Location | Description |
---|---|---|---|
ownerAccountId | string | path | The owner account's ID. |
id | string | path | The lock group's ID. |
forceRevokeGrants | boolean | query | Optional. Defaults to false . |
forceUnjoinLocks | boolean | query | Optional. Defaults to false . |
Response¶
204 No Content
Or, in case lock group ID is invalid:
404 lock group not found
Or, in case the lock group has locks assigned and forceUnjoinLocks
is false
:
400 lock group has locks assigned
Or, in case the lock group has active grants and forceRevokeGrants
is false
:
400 lock group has active grants
Get Grants for Lock Group¶
Get a queryable list of grants for the specified lock group.
Scope¶
read:grants
Parameters¶
Tip
The returned list can be filtered using OData query parameters.
Name | Type | Location | Description |
---|---|---|---|
ownerAccountId | string | path | The owner account's ID. |
id | string | path | The lock group's ID. |
Response¶
200 OK
[
{
"contact": {
"id": "1",
"ownerId": "1",
"comment": "A comment describing this contact.",
"ipId": null,
"ipUserId": null,
"email": "user1@tapkey.com",
"ipUserName": "user1@tapkey.com",
"isActive": true,
"title": "User One"
},
"boundCard": null,
"boundLock": {
"targetType": "Group",
"id": "1",
"physicalLockId": "DAAl1T7twFAiUeZ56tI=",
"title": "Office Building",
"description": "A description for the new lock group."
},
"owner": null,
"id": "1",
"boundLockId": "1",
"contactId": "1",
"validFrom": null,
"validBefore": null,
"timeRestrictionIcal": null,
"state": "Ok",
"active": true,
"boundCardId": null,
"customPayload": null
}
]
Get List of Lock Group Memberships¶
Get a list of the specified lock group's members.
Returns a list of locks that are part of the lock group or have been part of the lock group in the past. The state of the lock's membership can be deducted from the
joinStartDate
joinCompletedDate
leaveStartDate
leaveCompletedDate
properties. If the property is null, the respective action has not taken place yet. The diagram below demonstrates the lifecycle of a lock's group membership.
stateDiagram state "Initial" as initial: Lock not member of the group. state "Added" as joinStarted: Lock added, but not yet active. state "Joined" as joinCompleted: Lock added and active group member. state "Removed" as leaveStarted: Lock removed, but still active group member. state "Unjoined" as leaveCompleted: Lock not member of the group. [*] --> initial leaveCompleted --> [*] initial --> joinStarted: PUT Membership - joinStartedDate is set joinStarted --> joinCompleted: Sync lock - joinCompletedDate is set joinCompleted --> leaveStarted: DELETE Membership - leaveStartedDate is set leaveStarted --> leaveCompleted: Sync lock - leaveCompletedDate is set
Scope¶
read:grants
Parameters¶
Tip
The returned list can be filtered using OData query parameters.
Name | Type | Location | Description |
---|---|---|---|
ownerAccountId | string | path | The owner account's ID. |
lockGroupId | string | path | The lock group's ID. |
expand | string | path | Optional. A comma-separated list of expandable properties. |
includeUnboundLocks | string | path | Optional. Whether to return unbound locks or not. Defaults to false . |
Response¶
200 OK
[
{
"boundLock": null,
"lockGroup": null,
"lastSeenRclSerialNo": null,
"lastSeenRclUpdateDate": null,
"id": "1",
"lockGroupId": "1",
"boundLockId": "2",
"joinStartDate": "2020-03-03T15:53:03.587Z",
"joinCompletedDate": "2020-03-03T15:53:13.657Z",
"leaveStartDate": "2020-03-27T14:00:36.800Z",
"leaveCompletedDate": null
},
{
"boundLock": null,
"lockGroup": null,
"lastSeenRclSerialNo": null,
"lastSeenRclUpdateDate": null,
"id": "2",
"lockGroupId": "1",
"boundLockId": "2",
"joinStartDate": "2020-03-03T15:28:43.187Z",
"joinCompletedDate": "2020-03-03T15:38:23.940Z",
"leaveStartDate": null,
"leaveCompletedDate": null
}
]
Expandable properties¶
Bound lock¶
When passing boundLock
to the expand query parameter, the response will contain the following additional property:
"boundLock": {
"active": true,
"rclSerialNo": 13,
"rclDate": null,
"targetType": "Lock",
"id": "1",
"physicalLockId": "BADhB7Iu",
"title": "Entrance Door",
"description": "Description of Entrance Door."
}
Lock group¶
When passing lockGroup
to the expand query parameter, the response will contain the following additional property,
"lockGroup": {
"active": false,
"rclSerialNo": 5,
"rclDate": null,
"targetType": "Group",
"id": "1",
"physicalLockId": "DAAl1T7twFAiUeZ56tI=",
"title": "Office Building",
"description": "Description of the lock group."
}
Create Lock Group Membership¶
Create a new lock group membership.
Info
See
Scope¶
write:grants
Parameters¶
Name | Type | Location | Description |
---|---|---|---|
ownerAccountId | string | path | The owner account's ID. |
lockGroupId | string | path | The lock group's ID. |
Body¶
{
"boundLockId": "3"
}
Response¶
200 OK
{
"boundLock": null,
"lockGroup": null,
"lastSeenRclSerialNo": null,
"lastSeenRclUpdateDate": null,
"id": "5",
"lockGroupId": "1",
"boundLockId": "3",
"joinStartDate": "2020-03-03T15:53:03.587Z",
"joinCompletedDate": null,
"leaveStartDate": null,
"leaveCompletedDate": null
}
In case the specified lock is already a member of the group:
400 lock is already member of this group
In case the specified lock does not support lock grouping, or the lock group is restricted to locks having a newer firmware version:
400 the lock's protocol version is too old
In case the specified lock is already member of too many groups:
400 this lock is already member of n groups and therefore cannot join another group
If the provided bound lock ID is invalid:
404 bound lock not found
If the provided lock group ID is invalid:
404 lock group not found
Delete Lock Group Membership¶
Delete the specified lock group membership.
Info
See
Scope¶
write:grants
Parameters¶
Name | Type | Location | Description |
---|---|---|---|
ownerAccountId | string | path | The owner account's ID. |
lockGroupId | string | path | The lock group's ID. |
id | string | path | The lock group membership's ID. |
Response¶
204 No Content
Or, in case the lock group membership ID is invalid:
404 lock group membership not found