Lock Groups¶

Get List of Lock Groups¶

Get a list of this owner account's lock groups.

Scope¶

read:core:entities

Parameters¶

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¶

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/api/v1/Owners/{ownerAccountId}/LockGroups/

operation above.

Create Lock Group¶

Create a new lock group.

Scope¶

write:core:entities

Parameters¶

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¶

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 to true, 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 to false, the operation will fail if any member lock is in a state other than Unjoined. 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 to true, the revocation process will be started for the affected grants as part of this operation.
• If forceRevokeGrants is set to false, this operation will fail, if any active grants are assigned.

Scope¶

write:core:entities

Parameters¶

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¶

Response¶

200 OK

[
  {
    "contact": {
      "id": "1",
      "ownerId": "1",
      "comment": "A comment describing this contact.",
      "ipId": "tapkey",
      "ipUserId": null,
      "identifier": "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¶

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.

Scope¶

write:grants

Parameters¶

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.

Scope¶

write:grants

Parameters¶

Response¶

204 No Content

Or, in case the lock group membership ID is invalid:

404 lock group membership not found