Locks

Locks are a core part of DUSAW — the very reason DUSAW exists is to provide a way to manage locks. On this page, we'll dive into the different lock endpoints you can use to manage locks programmatically. We'll look at how to query, create, update, and delete locks.

The lock model

The lock model contains all the information about your locks. Only the lock's administrator is allowed to access the lock details.

Properties

Name
lockId
Type
integer
Description
The lock's unique identifier.
Name
lockName
Type
string
Description
The lock's name.
Name
lockAlias
Type
string
Description
The lock's alias.
Name
lockMac
Type
string
Description
The lock's MAC address.
Name
noKeyPwd
Type
string
Description
The Super Passcode, which belongs to the admin
Name
electricQuantity
Type
integer
Description
Lock Battery Level
Name
featureValue
Type
String
Description
Indicates the lock's features.
Name
timezoneRawOffset
Type
Long
Description
The offset between your timezone and UTC, in millisecond
Name
modelNum
Type
String
Description
The lock's model number.
Name
hardwareRevision
Type
String
Description
The lock's hardware revision.
Name
firmwareRevision
Type
String
Description
The lock's firmware revision.
Name
autoLockTime
Type
integer
Description
Auto Lock Time in seconds
Name
lockSound
Type
integer
Description
Lock Sound: 0 - unknown, 1 - on, 2 - off
Name
privacyLock
Type
integer
Description
Privacy lock: 0 - unknown, 1 - on, 2 - off
Name
tamperAlert
Type
integer
Description
Tamper Alert: 0 - unknown, 1 - on, 2 - off
Name
resetButton
Type
integer
Description
Reset Button: 0 - unknown, 1 - on, 2 - off
Name
openDirection
Type
integer
Description
Open Direction: 0 - unknown, 1 - left, 2 - right
Name
passageMode
Type
integer
Description
Passage Mode: 0 - unknown, 1 - on, 2 - off
Name
passageModeAutoUnlock
Type
integer
Description
Passage Mode Auto Unlock: 1 - on, 2 - off
Name
passageModeAutoUnlock
Type
integer
Description
Passage Mode Auto Unlock: 1 - on, 2 - off
Name
date
Type
long
Description
Lock's initialisation timestamp in milliseconds

Lock Object

{
  "lockId": 865759,
  "lockName":"DUS356_c15c7c",
  "lockAlias":"Side Door Lock",
  "lockMac": "C6:20:E6:9J:8W:Q6",
  "electricQuantity": 86,
  "featureValue":"3G0421S4Q5Q3",
  "hasGateway": 1,
  "lockData": "xxxxxxxxxxxxx",
  "groupId": 789,
  "groupName": "The Office",
  "date": 1672689580361,
}

GET/api/v1/lock/list

List all locks

This endpoint allows you to retrieve a paginated list of all your locks.

Required attributes

Name
pageNo
Type
integer
Description
Page number
Name
pageSize
Type
integer
Description
Page size minimum 10, maximum 1000

Optional attributes

Name
lockAlias
Type
string
Description
Search by lock alias

Request

GET

/api/v1/lock/list

curl --location --request GET 'https://api.dusaw.com/api/v1/lock/list?pageNo=1&pageSize=20' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {token}'

Response

{
  "list": [
    ...
    {
      "lockId": 865759,
      "lockName":"DUS356_c15c7c",
      "lockAlias":"Side Door Lock",
      "lockMac": "C6:20:E6:9J:8W:Q6",
      "electricQuantity": 86,
      "featureValue":"3G0421S4Q5Q3",
      "hasGateway": 1,
      "lockData": "xxxxxxxxxxxxx",
      "groupId": 789,
      "groupName": "The Office",
      "date": 1672689580361,
    }
    ...
  ],
  "pageNo":1,
  "pageSize":10,
  "pages":3,
  "total":25
}

GET/api/v1/lock/hotel-list

List all locks by hotel

This endpoint allows you to retrieve a paginated list of the locks that belong to your hotel.

Required attributes

Name
pageNo
Type
integer
Description
Page number (minimum 1)
Name
pageSize
Type
integer
Description
Page size minimum 10, maximum 1000

Optional attributes

Name
lockAlias
Type
string
Description
Search by lock alias

Request

GET

/api/v1/lock/hotel-list

curl --location --request GET 'https://api.dusaw.com/api/v1/lock/hotel-list?pageNo=1&pageSize=20' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {token}'

Response

{
  "list": [
    ...
    {
      "lockId": 865759,
      "lockName":"DUS356_c15c7c",
      "lockAlias":"Side Door Lock",
      "lockMac": "C6:20:E6:9J:8W:Q6",
      "electricQuantity": 86,
      "featureValue":"3G0421S4Q5Q3",
      "hasGateway": 1,
      "lockData": "xxxxxxxxxxxxx",
      "groupId": 789,
      "groupName": "The Office",
      "date": 1672689580361,
    }
    ...
  ],
  "pageNo":1,
  "pageSize":10,
  "pages":3,
  "total":25
}

GET/api/v1/lock/state

Lock State

Get the lock's current state (locked, unlocked).

Only supported by locks connected to a gateway.

This endpoint allows you to retrieve the lock's current open state.

Required attributes

Name
lockId
Type
integer
Description
The lock's unique identifier.

Request

GET

/api/v1/lock/state

curl --location --request GET 'https://api.dusaw.com/api/v1/lock/state?lockId=76133538' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'

Response

{
  "state": "locked"
}

POST/api/v1/lock/lock

Lock It

Lock the lock. The lock will be locked if it is unlocked, otherwise nothing will happen.

Only supported by locks connected to a gateway and with remote unlock enabled.

This endpoint allows you to lock the lock.

Required attributes

Name
lockId
Type
integer
Description
The lock's unique identifier.

Request

POST

/api/v1/lock/lock

curl --location --request POST 'https://api.dusaw.com/api/v1/lock/lock?lockId=76133538' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'

Response

{
  "success": true
}

POST/api/v1/lock/unlock

Unlock It

Unlock the lock. The lock will be unlocked if it is locked, otherwise nothing will happen.

Only supported by locks connected to a gateway and with remote unlock enabled.

This endpoint allows you to unlock the lock.

Required attributes

Name
lockId
Type
integer
Description
The lock's unique identifier.

Request

POST

/api/v1/lock/unlock

curl --location --request POST 'https://api.dusaw.com/api/v1/lock/unlock?lockId=76133538' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'

Response

{
  "success": true
}

POST/api/v1/lock/set-auto-lock-timer

Set Auto Lock Timer

Set the auto lock timer. The lock will automatically lock after the specified number of seconds.

Only supported by locks connected to a gateway.

This endpoint allows you to set the auto lock timer.

Required attributes

Name
lockId
Type
integer
Description
The lock's unique identifier.
Name
seconds
Type
integer
Description
The number of seconds to wait before automatically locking the lock (minimum 3).

Request

POST

/api/v1/lock/set-auto-lock-timer

curl --location --request POST 'https://api.dusaw.com/api/v1/lock/set-auto-lock-timer?lockId=76133538&seconds=5' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'

Response

{
  "success": true
}

GET/api/v1/lock/battery

Lock Battery Percentage

Get the lock's current battery percentage.

Only supported by locks connected to a gateway.

This endpoint allows you to retrieve the lock's current battery percentage.

Required attributes

Name
lockId
Type
integer
Description
The lock's unique identifier.

Request

GET

/api/v1/lock/battery

curl --location --request GET 'https://api.dusaw.com/api/v1/lock/battery?lockId=76133538' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'

Response

{
  "BatteryPercentage": 100
}

GET/api/v1/lock/records

Unlock records

Retrieve lock records stored on the server by filtering based on operation timestamps.

Note: The server retains lock records from the past 6 months only. Queries for records older than 6 months are not supported.

This endpoint allows you to retrieve a paginated list of all lock records for specific lock.

Required attributes

Name
lockId
Type
integer
Description
The lock's unique identifier.
Name
pageNo
Type
integer
Description
Page number
Name
pageSize
Type
integer
Description
Page size minimum 10, maximum 1000

Optional attributes

Name
startDate
Type
long
Description
Search starting Time (in milliseconds). Must be later than 6 hours ago.
Name
endDate
Type
long
Description
Search ending Time (in milliseconds). Required when startDate is provided, and must be greater than startDate.

Request

GET

/api/v1/lock/records

curl --location --request GET 'https://api.dusaw.com/api/v1/lock/records?lockId=76133538&pageNo=1&pageSize=20' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'

Response

{
  "list": [
  ...
{
  "recordId": 1212124614,
  "lockId": 76133538,
  "serverDate": 1682455009000,
  "recordType": "Unlock by passcode",
  "success": 1,
  "keyboardPwd": "47613715349504",
  "lockDate": 1682455018000,
  "username": "John"
}
  ...
  ],
  "pageNo":1,
  "pageSize":10,
  "pages":3,
  "total":25
}

POST/api/v1/lock/share

Create a share token for a lock. A share token generates a URL that can be used to grant access to the lock without sharing the lock's administrative credentials. Optionally, the share link can be emailed to a recipient.

The lock must be accessible with your account, connected to a gateway, and have "Remote Unlock" enabled in the Sciener app. Otherwise the request fails with a 422 error.

This endpoint allows you to create a share token for one of your locks.

Required attributes

Name
lockId
Type
integer
Description
The lock's unique identifier.
Name
type
Type
string
Description
The share type. One of permanent, timed, or one_time.

Optional attributes

Name
expiresAt
Type
string
Description
The expiry date/time of the share (ISO 8601). Must be in the future. Required when type is timed.
Name
email
Type
string
Description
The recipient's email address. Required when sendEmail is true.
Name
sendEmail
Type
boolean
Description
Whether to email the share link to the recipient. Defaults to false.

Request

POST

/api/v1/lock/share

curl --location --request POST 'https://api.dusaw.com/api/v1/lock/share' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
  "lockId": 76133538,
  "type": "timed",
  "expiresAt": "2025-12-31T23:59:59Z",
  "email": "guest@example.com",
  "sendEmail": true
}'

Response

{
  "success": true,
  "data": {
    "id": 12,
    "token": "aB3dEf6HiJk9LmNoPqRsTuVwXyZ01234",
    "url": "https://api.dusaw.com/lock-share/aB3dEf6HiJk9LmNoPqRsTuVwXyZ01234",
    "lockId": 76133538,
    "lockAlias": "Side Door Lock",
    "type": "timed",
    "expiresAt": "2025-12-31T23:59:59.000000Z",
    "email": "guest@example.com",
    "sentAt": "2025-08-07T14:52:00.000000Z",
    "createdAt": "2025-08-07T14:52:00.000000Z"
  }
}

GET/api/v1/lock/shares

List lock shares

Retrieve share tokens you have created, including their current active status. When lockId is provided, only shares for that lock are returned; otherwise all your share tokens are returned.

This endpoint allows you to retrieve your share tokens.

Optional attributes

Name
lockId
Type
integer
Description
The lock's unique identifier. When omitted, all your share tokens are returned.

Request

GET

/api/v1/lock/shares

curl --location --request GET 'https://api.dusaw.com/api/v1/lock/shares?lockId=76133538' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}'

Response

{
  "success": true,
  "data": [
    {
      "id": 12,
      "token": "aB3dEf6HiJk9LmNoPqRsTuVwXyZ01234",
      "url": "https://api.dusaw.com/lock-share/aB3dEf6HiJk9LmNoPqRsTuVwXyZ01234",
      "lockId": 76133538,
      "lockAlias": "Side Door Lock",
      "type": "timed",
      "expiresAt": "2025-12-31T23:59:59.000000Z",
      "usedAt": null,
      "email": "guest@example.com",
      "sentAt": "2025-08-07T14:52:00.000000Z",
      "usesCount": 0,
      "isActive": true,
      "createdAt": "2025-08-07T14:52:00.000000Z"
    }
  ]
}

DELETE/api/v1/lock/share

Revoke a previously created share token. Once revoked, the share URL can no longer be used to access the lock.

This endpoint allows you to revoke a share token for one of your locks.

Required attributes

Name
token
Type
string
Description
The share token to revoke.

Request

DELETE

/api/v1/lock/share

curl --location --request DELETE 'https://api.dusaw.com/api/v1/lock/share' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
  "token": "aB3dEf6HiJk9LmNoPqRsTuVwXyZ01234"
}'

Response

{
  "success": true
}