Skip to content

Lock Groups

Get List of Lock Groups

GET/Owners/{ownerAccountId}/LockGroups

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

PUT/Owners/{ownerAccountId}/LockGroups

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

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

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

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/Owners/{ownerAccountId}/LockGroups/{id}/Grants

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

PUT/Owners/{ownerAccountId}/LockGroups/{lockGroupId}/Memberships

Create a new lock group membership.

Info

See

for more information about a lock's group membership lifecycle.

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/Owners/{ownerAccountId}/LockGroups/{lockGroupId}/Memberships/{id}

Delete the specified lock group membership.

Info

See

for more information about a lock's group membership lifecycle.

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