Smart Lock Open APIs

This topic describes the processes and APIs for smart lock development. The smart lock cloud development allows you to implement lock services on your self-built servers such as WeChat mini program, web system, and H5 pages.

Integration process

Before you integrate with vertical resources of smart locks, you need to register as a Tuya developer. For more information, see Quick Start.

The following figure shows how to implement cloud development of smart locks.

Applicable categories

Protocol	Applicable category
Wi-Fi	Wi-Fi residential lock pro, Wi-Fi residential lock, and Wi-Fi safe box.
Bluetooth low energy	Bluetooth lock, including the Bluetooth lock with gateway features.
Zigbee	Zigbee residential lock pro and Zigbee residential lock.

API logs

You can query API call logs for the last seven days. You can provide API request parameters by submitting a service ticket. Tuya will contact you within two hours. For urgent issues, you can contact project managers.

API list

The following table lists the APIs that support smart lock services.

Request method	API	Description
POST	/v1.0/devices/{device_id}/door-lock/password-ticket	Get a temporary key for password encryption.
POST	/v1.0/devices/{device_id}/door-lock/temp-password	Create a temporary password. A periodic password is supported.
POST	/v2.0/devices/{device_id}/door-lock/temp-password	Create an unnamed temporary password. A periodic password is supported.
POST	/v1.0/devices/{device_id}/door-lock/issue-password	Synchronize passwords.
GET	/v1.0/devices/{device_id}/door-lock/temp-password/{password_id}	Get the information about a temporary password.
GET	/v1.0/devices/{device_id}/door-lock/temp-passwords	Get a list of temporary passwords.
GET	/v1.0/smart-lock/devices/{device_id}/stand-by-lock-temp-passwords	Get a list of keepalive temporary passwords.
PUT	/v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/modify-password	Modify a temporary password.
PUT	/v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/freeze-password	Freeze a temporary password.
PUT	/v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/unfreeze-password	Unfreeze a temporary password.
DELETE	/v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}	Delete a temporary password.
POST	/v1.0/devices/{device_id}/door-lock/offline-temp-password	Get an offline password.
POST	/v1.1/devices/{device_id}/door-lock/offline-temp-password	Get an offline password v1.1.
PUT	/v1.0/devices/{device_id}/door-lock/offline-temp-password/{password_id}	Update the name of an offline password.
GET	/v1.0/devices/{device_id}/door-lock/dynamic-password	Get a dynamic password.
POST	/v1.0/devices/{device_id}/user	Add a device user (not a home user).
PUT	/v1.0/devices/{device_id}/users/{user_id}	Modify a device user (not a home user).
PUT	/v1.0/smart-lock/devices/{device_id}/users/{user_id}/actions/role	Update the role of a device user.
DELETE	/v1.0/devices/{device_id}/users/{user_id}	Delete a device user (not a home user).
GET	/v1.0/devices/{device_id}/users/{user_id}	Query the information about a device user (not a home user ).
GET	/v1.1/devices/{device_id}/users/{user_id}	Query the information about a device user (v1.1), including the current user.
GET	/v1.0/devices/{device_id}/users	Query a list of users by device ID (not a home user).
GET	/v1.1/devices/{device_id}/users	Query a list of users by device ID (not a home user)-v1.1.
POST	/v1.0/devices/{device_id}/device-lock/users/{user_id}/allocate	Assign a password to a device user (not a home user).
POST	/v1.0/devices/{device_id}/door-lock/opmodes/actions/allocate	Assign multiple unlocking methods to users.
GET	/v1.0/smart-lock/users/{uid}/devices	Get the devices linked with a specified user account.
GET	/v1.0/devices/{device_id}/door-lock/user-types/{user_type}/users/{user_id}/assigned-keys	Get a list of unlocking methods linked with a specified user (home user only).
GET	/v1.0/devices/{device_id}/door-lock/unassigned-keys	Get a list of unlocking methods that are not linked with users (home user only).
POST	/v1.0/smart-lock/devices/{device_id}/opmodes/actions/sync	Sync unlocking methods by the cloud.
PUT	/v1.0/devices/{device_id}/door-lock/actions/entry	Enroll unlocking methods (home user only).
DELETE	/v1.0/devices/{device_id}/door-lock/user-types/{user_type}/users/{user_id}/unlock-types/{unlock_type}/keys/{unlock_no}	Delete unlocking methods (home user only).
PUT	/v1.0/devices/{device_id}/door-lock/unlock-types/{unlock_type}/actions/cancel	Cancel unlocking method enrollment (home user only).
PUT	/v1.0/devices/{device_id}/door-lock/opmodes/{unlock_sn}	Update the names of unlocking methods.
PUT	/v1.0/devices/{device_id}/door-lock/unlock-types/{unlock_type}/keys/{unlock_no}/hijack	Set an unlocking method to trigger a duress alarm (home user only).
GET	/v1.0/devices/{device_id}/door-lock/open-logs	Query the unlocking records.
*GET	/v1.1/devices/{device_id}/door-lock/open-logs	Query the unlocking records.
GET	/v1.0/devices/{device_id}/door-lock/alarm-logs	Get the alert records.
*GET	/v1.1/devices/{device_id}/door-lock/alarm-logs	Get the alert records.
GET	/v1.0/devices/{device_id}/door-lock/records	Get the alert records and unlocking records.
POST	/v1.0/devices/{device_id}/door-lock/records/{record_id}/actions/allocate	Link a specified record with a user.
POST	/v1.0/devices/{device_id}/door-lock/temp-passwords/rest-password	Clear temporary passwords.
GET	/v1.0/devices/{device_id}/door-lock/remote-unlocks	Get the remote unlocking methods supported by a lock.
POST	/v1.0/devices/{device_id}/door-lock/remote-unlock/config	Set a switch for a remote unlocking method.
POST	/v1.0/devices/{device_id}/door-lock/open-door	Unlock a door with password.
POST	/v1.0/devices/{device_id}/door-lock/password-free/open-door	Unlock a door without password.
POST	/v1.1/devices/{device_id}/door-lock/password-free/open-door	Unlock a door without password (v1.1). A certain channel can be specified for unlocking.
PUT	/v1.0/devices/{device_id}/door-lock/password-free/open-door/cancel	Revoke a password-free unlocking.
GET	/v1.0/devices/{device_id}/door-lock/latest/media/url	Get the cover image of the last remote unlocking or alert.
POST	/v1.0/devices/{device_id}/door-lock/advanced-password	Set an advanced password.
GET	/v1.0/devices/{device_id}/door-lock/advanced-password	Query an advanced password.
GET	/v1.0/devices/{device_id}	Get the information about a specified device. You get the local key to encrypt and decrypt the password.
GET	/v1.0/smart-lock/devices/{device_id}/users	Get a list of home users and unlocking methods.
PUT	/v1.0/smart-lock/devices/{device_id}/users/{user_id}/schedule	Update the validity period of a home user.
GET	/v1.0/smart-lock/devices/{device_id}/albums-media	Get a list of albums.
GET	/v1.0/devices/{device_id}/door-lock/absent-users	Get a list of removed users.
POST	/v1.0/smart-lock/devices/{device_id}/users/{user_ids}/actions/delete-users-issue	Delete the information about users.
GET	/v1.0/smart-lock/devices/{device_id}/opmodes/{user_id}	Get a list of unlocking methods applicable to a specified user.
DELETE	/v1.0/smart-lock/devices/{device_id}/unlock-types/{unlock_type}/keys/{unlock_sn}/hijack	Delete the duress alarm of unlocking methods.
POST	/v1.0/smart-lock/devices/{device_id}/password-ticket	Get a temporary key for password encryption.
POST	/v1.0/smart-lock/devices/{device_id}/password-free/door-operate	Remote locking and unlocking without password.
GET	/v1.0/smart-lock/devices/{device_id}/media-view-times	Query the video views of the current lock.
POST	/v1.0/smart-lock/devices/{device_id}/media-view-times	Add one video view to a specified video file generated by the current lock each time this video is viewed.
POST	/v1.0/smart-lock/devices/{device_id}/opmodes/{opmode_id}/attribute/{attribute}/opmode-attr	Enable the image capturing attribute.

Note: The APIs with an asterisk (*) only apply to legacy versions.

For more information, see the following documentation.

Documentation	Applicable feature
Standard Instruction Set for Smart Locks	Lock settings, such as volume and language.
Device Control	Get the standard instruction set of a device.
Global Error Codes	A list of error codes that might be returned during your development.

Create passwords

• The following figure shows how password creation works for a Wi-Fi lock.

  

• The following figure shows how password creation works for a Zigbee lock.

  

  • The following describes the process flow when the Zigbee lock works fine:

    • The caller calls the API to create a password.
    • The cloud sends a password to the gateway.
    • The gateway sends the password to the lock.
    • The lock responds to the gateway: Password settings succeeded.
    • The gateway reports the password status: Password settings succeeded.
    • The cloud updates password status: Password settings succeeded.
    • The caller polls the password status until it gets the status of success or failure. The polling times out after 25 seconds.

  • The following describes the process flow when an exception occurs in the Zigbee lock.

    • The caller calls the API to get the lock information.
    • The caller calls the API to create a password that is encrypted with the local key.
    • The cloud sends a password to the gateway.
    • The gateway sends the password to the lock.
    • The lock does not respond.
    • The gateway resends the password three times.
    • The gateway reports the password status: Password settings failed.
    • The cloud updates the password status: Password settings failed.
    • The caller polls the password status until it gets the status of success or failure. The polling times out after 25 seconds.

Encrypt passwords

Wi-Fi access control devices

Users

• The users who perform device pairing are users of a home.
• Other users are not users of a home.

Roles and permissions

Role types of Wi-Fi access control devices

• Super administrator (device owner)
• Administrator
• Common user

Recommended definitions of permissions

We recommend downward management. A role can view and operate the subordinate roles, but cannot view or operate the roles at the same level.

• Device owners can add, update, and delete any user’s data, but cannot delete themselves.
• An administrator can manage their own data and common users’ data, but cannot view or manage other administrators’ data.
• Common users can only view and operate their own data.

Smart lock APIs

Get a temporary key for password encryption

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock
• Zigbee lock for hotel use
• Wi-Fi lock with video talk

API endpoint

POST /v1.0/devices/{device_id}/door-lock/password-ticket

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/password-ticket

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a temporary password.

result

Parameter	Type	Description
ticket_id	String	The ID of a specified temporary key.
ticket_key	String	The temporary key. It can be used after decryption with AES using the accessKey that is issued by the platform.
expire_time	Long	The remaining validity period.

Sample response on success

{
    "result": {
        "expire_time": 360,
        "ticket_id": "9wxxoLM",
        "ticket_key": "901CC35A67DA3429C38E9622xxxxx3EAE1CE333462356D257FD1D3E5C"
    },
    "success": true,
    "t": 1592899848757
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Create a temporary password

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock
• Zigbee lock for hotel use
• Keepalive lock
• Wi-Fi lock with video talk
• Wi-Fi access control devices

API endpoint

POST /v1.0/devices/{device_id}/door-lock/temp-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
Name	String	BODY	The name of a specified temporary password.	Yes
password	String	BODY	The length of the original password is seven digits for Wi-Fi locks and six digits for Zigbee locks and Bluetooth locks. The password is encrypted by using the AES-128 algorithm with ECB mode and PKCS7Padding. To get the original key, decrypt the temporary key ticket_key with AES using the accessKey that is issued by the platform. The output format is hex.	Yes
effective_time	Long	BODY	The 10-digit timestamp of the effective time. Unit: seconds (s).	Yes
invalid_time	Long	BODY	The 10-digit timestamp of the expiration time. Unit: seconds (s).	Yes
password_type	String	BODY	The password is encrypted using a ticket.	Yes
ticket_id	String	BODY	The ID of a specified temporary key.	Yes
phone	String	BODY	The mobile phone number.	No
type	Integer	BODY	Indicates the number of times a password can be used. Valid values: 1: A password can only be used once before it expires. 0: A password can be used as many times as needed before it expires.	This field is required for Zigbee locks.
time_zone	String	BODY	The time zone. This field is required if you use the periodic password feature.	No
schedule_list	List	BODY	The parameter list of the periodic password feature.	No

schedule_list

Parameter	Type	Parameter type	Description	Required
effective_time	Long	BODY	The time when a password becomes effective on that day, in minutes.	Yes
invalid_time	Long	BODY	The time when a password expires on that day, in minutes.	Yes
working_day	Int	BODY	The day of the week. Each value accumulates. Valid values: 1: Sunday 2: Monday 4: Tuesday 8: Wednesday 16: Thursday 32: Friday 64: Saturday	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/temp-password

{
    "password": "956FAD7xxxxxx09C68E168B77",
    "password_type": "ticket",
    "ticket_id": "xxxxxx",
    "effective_time": 1579156726,
    "invalid_time": 1579243126,
    "name":"test",
    "phone": 11233213,
    "time_zone":"",
    "schedule_list":[{
        "effective_time": 720,
        "invalid_time": 1080,
        "working_day":  0
    }]
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a temporary password.

result

Parameter	Type	Description
id	Long	The ID of a specified temporary password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "id": 124367346
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Create an unnamed temporary password

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock
• Zigbee lock for hotel use
• Wi-Fi lock with video talk

API endpoint

POST /v2.0/devices/{device_id}/door-lock/temp-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password	String	BODY	The length of the original password is seven for Wi-Fi locks and six for Zigbee locks and Bluetooth locks. The password is encrypted by using the AES-128 algorithm with ECB mode and PKCS7Padding. To get the original key, decrypt the temporary key ticket_key with AES using the accessKey that is issued by the platform.	Yes
effective_time	Long	BODY	The 10-digit timestamp of the effective time. Unit: seconds (s).	Yes
invalid_time	Long	BODY	The 10-digit timestamp of the expiration time. Unit: seconds (s).	Yes
password_type	String	BODY	The password is encrypted using a ticket.	Yes
ticket_id	String	BODY	The ID of a specified temporary key.	Yes
phone	String	BODY	The mobile phone number.	No
type	Integer	BODY	Indicates the number of times a password can be used. Valid values: 1: A password can only be used once before it expires. 0: A password can be used as many times as needed before it expires.	This field is required for Zigbee locks.
time_zone	String	BODY	The time zone. This field is required if you use the periodic password feature.	No
schedule_list	List	BODY	The parameter list of the periodic password feature.	No

schedule_list

Parameter	Type	Parameter type	Description	Required
effective_time	Long	BODY	The time when a password becomes effective on that day, in minutes.	Yes
invalid_time	Long	BODY	The time when a password expires on that day, in minutes.	Yes
working_day	Int	BODY	The day of the week. Each value accumulates. Valid values: 1: Sunday 2: Monday 4: Tuesday 8: Wednesday 16: Thursday 32: Friday 64: Saturday	Yes

Sample request

POST /v2.0/devices/vdevo153459260090544/door-lock/temp-password

{
    "password": "956FAD7xxxxxx09C68E168B77",
    "password_type": "ticket",
    "ticket_id": "xxxxxx",
    "effective_time": 1579156726,
    "invalid_time": 1579243126,
    "phone": 11233213,
    "time_zone":"",
    "schedule_list":[{
        "effective_time": 720,
        "invalid_time": 1080,
        "working_day":  0
    }]
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a temporary password.

result

Parameter	Type	Description
id	Long	The ID of a specified temporary password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "id": 124367346
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Synchronize passwords

Applicable lock types

• Zigbee lock

Note: After a password is created for a Zigbee lock, if the password status is in configuring, you can call this API to synchronize the password in configuring to the lock. For a single device, this API can only be called once within 60 seconds.

API endpoint

POST /v1.0/devices/{device_id}/door-lock/issue-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password_id	Long	BODY	The password ID. If this field is left blank, all the passwords currently in configuring will be sent to the lock.	No

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/issue-password

{
   "password_id":""
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get the information about a temporary password

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock
• Zigbee lock for hotel use

API endpoint

GET /v1.0/devices/{device_id}/door-lock/temp-password/{password_id}

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password_id	Long	URI	The password ID.	Yes

Sample request

GET /v1.0/devices/vdevo153459260090544/door-lock/temp-password/xxxx

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a temporary password.

result

Parameter	Type	Description
id	Long	The ID of a specified temporary password.
Name	String	The name of a specified temporary password.
phase	Integer	The status of a specified temporary password.
effective_time	Long	The 10-digit timestamp of the effective time.
invalid_time	Long	The 10-digit timestamp when a temporary password expires.
phone	String	The mobile phone number.
time_zone	String	The time zone.
delivery_status	Integer	The operation status. Valid values: 1: The password is being configured. 2: Password configuration succeeds. 3: Password configuration fails. 4: The password already exists. 5: The number of passwords exceeds the limit allowed. 6: The validity period overlaps with that of another password. Note that this result is only available for Zigbee locks.
schedule_list	List	The parameter list of the periodic password feature.

schedule_list

Parameter	Type	Description
effective_time	Long	The time when a password becomes effective on that day, in minutes.
invalid_time	Long	The time when a password expires on that day, in minutes.
working_day	Int	The day of the week. Each value accumulates. Valid values: 1: Sunday 2: Monday 4: Tuesday 8: Wednesday 16: Thursday 32: Friday 64: Saturday

phase

• Zigbee lock:
  • 1: To be created
  • 2: Normal
  • 3: Frozen
  • 4: Deleted
  • 5: Creation failed
• Wi-Fi lock:
  • 0: Deleted
  • 1: To be sent
  • 2: Sent
  • 3: To be deleted
• Bluetooth lock:
  • 0: Deleted
  • 1: To be sent
  • 2: Sent
  • 3: To be deleted
  • 7: Failed to send

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "id": 1001, // The primary key of a temporary password.
        "effective_time": 1530841779, // The 10-digit timestamp of the effective time.
        "invalid_time": 1530881779, // The 10-digit timestamp of the expiration time.
        "name": "Tenant A's password", // The name of a temporary password.
        "phase": 1, // The password status.
        "phone": "123547127362",
        "time_zone":"Asia/Shanghai",
        "delivery_status": 1
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get a list of temporary passwords

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Zigbee lock for hotel use
• Bluetooth lock
• Wi-Fi lock with video talk

API endpoint

GET /v1.0/devices/{device_id}/door-lock/temp-passwords

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
valid	Boolean	URL	Specifies whether a password is valid.	No

Sample request

GET /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords?valid=true

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about the deleted password.

result

Parameter	Type	Description
id	Long	The ID of a specified temporary password.
Name	String	The name of a specified temporary password.
phase	Integer	The status of a specified temporary password.
effective_time	Long	The 10-digit timestamp of the effective time.
invalid_time	Long	The 10-digit timestamp when a temporary password expires.
phone	String	The mobile phone number.
time_zone	String	The time zone.
delivery_status	Integer	The operation status. Valid values: 1: The password is being configured. 2: Password configuration succeeds. 3: Password configuration fails. 4: The password already exists. 5: The number of passwords exceeds the limit allowed. 6: The validity period overlaps with that of another password. Note that this result is only available for Zigbee locks.
schedule_list	List	The parameter list of the periodic password feature.

schedule_list

Parameter	Type	Description
effective_time	Long	The time when a password becomes effective on that day, in minutes.
invalid_time	Long	The time when a password expires on that day, in minutes.
working_day	Int	The day of the week. Each value accumulates. Valid values: 1: Sunday 2: Monday 4: Tuesday 8: Wednesday 16: Thursday 32: Friday 64: Saturday

phase

• Zigbee lock:
  • 1: To be created
  • 2: Normal
  • 3: Frozen
  • 4: Deleted
  • 5: Creation failed
• Wi-Fi lock:
  • 0: Deleted
  • 1: To be sent
  • 2: Sent
  • 3: To be deleted
• Bluetooth lock:
  • 0: Deleted
  • 1: To be sent
  • 2: Sent
  • 3: To be deleted
  • 7: Failed to send

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": [
        {
            "password_id": 1001, // The primary key of a temporary password.
            "effective_time": 1530841779, // The 10-digit timestamp of the effective time.
            "invalid_time": 1530881779, // The 10-digit timestamp of the expiration time.
            "name": "Tenant A's password", // The name of a temporary password.
            "phase": 1, // The password status.
            "phone": "123547127362",
            "time_zone":"Asia/Shanghai",
            "delivery_status": 1
        }
    ]
}

Get a list of temporary passwords of keepalive locks

Applicable lock types

• Keepalive Wi-Fi locks
• Wi-Fi access control devices

API endpoint

GET /v1.0/smart-lock/devices/{device_id}/stand-by-lock-temp-passwords

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
valid	Boolean	URL	Specifies whether a password is valid.	No
lastRowKey	String	URL	The last row key when you query the records on pages. The value is from the last_row_key of the returned result, and it is empty when no value is returned.	No
pageSize	int	URL	The number of records returned on each page.	No

Sample request

GET /v1.0/smart-lock/devices/vdevo12454656****/stand-by-lock-temp-passwords?valid=true&last_row_key=&page_size=10

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about the deleted password.

result

Parameter	Type	Description
password_id	Long	The ID of a specified temporary password.
Name	String	The name of a specified temporary password.
gmt_create	Long	The 10-digit timestamp when a temporary password is created. Unit: seconds.
effective_time	Long	The 10-digit timestamp of the effective time.
expired_time	Long	The 10-digit timestamp when a temporary password expires.
operate	String	The operation type. Valid values: ADD: Add a password. MODIFY: Modify a password. DELETE: Delete a password.
delivery_status	String	The delivery status. Valid values: ONGOING: The password is being sent. SUCCESS: The password is successfully sent. FAILED: Failed to send the password.
effective_flag	int	The effective status. Valid values: 0: The password is ineffective. 1: The password is taking effect. 2: The password will take effect at the specified time.
schedule_details	List	The parameter list of the periodic password feature.

schedule_list

Parameter	Type	Description
start_minute	int	The time when a password becomes effective on that day, in minutes. Maximum value: 1440.
end_minute	int	The time when a password expires on that day, in minutes. Maximum value: 1440.
working_day	Int	The day of the week. Each value accumulates. Valid values: 1: Sunday 2: Monday 4: Tuesday 8: Wednesday 16: Thursday 32: Friday 64: Saturday
time_zone_id	String	The time zone.

Sample response on success

{
  "has_more": false,
  "last_row_key": "ABCDEFG",
  "records": [
    {
      "delivery_status": "SUCCESS",
      "effective_flag": 1,
      "effective_time": 1628006400,
      "expired_time": 1628265540,
      "gmt_create": 1628088594,
      "name": "369369",
      "operate": "CREATE",
      "password_id": 3351004,
      "phone": "",
      "pwd_type_code": "temp",
      "schedule_details": [
        {
          "all_day": false,
          "start_minute": 0,
          "end_minute": 2359,
          "working_day": 101
        }
      ],
      "sn": 0
    }
  ]
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "System exception. Contact the administrator."
}

Modify a temporary password

Applicable lock types

• All-in-one Wi-Fi lock
• All-in-one Zigbee lock
• Bluetooth lock (password change is not supported)
• Zigbee lock for hotel use
• Keepalive Wi-Fi locks
• Wi-Fi lock with video talk
• Wi-Fi access control devices

API endpoint

PUT /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/modify-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password_id	Long	URI	The password ID.	Yes
password	String	BODY	The length of the original password is seven for Wi-Fi locks and six for Zigbee locks. Bluetooth locks do not support password change. The password is encrypted by using the AES-128 algorithm with ECB mode and PKCS7Padding. To get the original key, decrypt the temporary key ticket_key with AES using the accessKey that is issued by the platform.	Yes
effective_time	Long	BODY	The 10-digit timestamp of the effective time. Unit: seconds (s).	Yes
invalid_time	Long	BODY	The 10-digit timestamp of the expiration time. Unit: seconds (s).	Yes
password_type	String	BODY	The password is encrypted using a ticket.	Yes
ticket_id	String	BODY	The ID of a specified temporary key.	Yes
phone	String	BODY	The mobile phone number.	No
type	Integer	BODY	Indicates the number of times a password can be used. Valid values: 1: A password can only be used once before it expires. 0: A password can be used as many times as needed before it expires.	This field is required for Zigbee locks.
time_zone	String	BODY	The time zone. This field is required if you use the periodic password feature.	No
schedule_list	List	BODY	The parameter list of the periodic password feature.	No

schedule_list

Parameter	Type	Parameter type	Description	Required
effective_time	Long	BODY	The time when a password becomes effective on that day, in minutes.	Yes
invalid_time	Long	BODY	The time when a password expires on that day, in minutes.	Yes
working_day	Int	BODY	The day of the week. Each value accumulates. Valid values: 1: Sunday 2: Monday 4: Tuesday 8: Wednesday 16: Thursday 32: Friday 64: Saturday	Yes

Sample request

PUT /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords/{password_id}/modify-password

{
   "phone":"",
   "effective_time":"",
   "invalid_time":"",
   "password":"",
   "password_type":"ticket",
   "ticket_id":"xxx"
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about the deleted password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result":true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Freeze a temporary password

Applicable lock types

• Zigbee lock

API endpoint

PUT /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/freeze-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password_id	String	URI	The password ID.	Yes

Sample request

PUT /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords/xxx/freeze-password

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about the deleted password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result":true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Unfreeze a temporary password

Applicable lock types

• Zigbee lock

API endpoint

PUT /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}/unfreeze-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password_id	String	URI	The password ID.	Yes

Sample request

PUT /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords/xxx/unfreeze-password

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about the deleted password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result":true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Delete a temporary password

Applicable lock types

• All-in-one Wi-Fi lock
• All-in-one Zigbee lock
• Zigbee lock for hotel use
• Bluetooth lock
• Keepalive Wi-Fi locks
• Wi-Fi lock with video talk
• Wi-Fi access control devices

API endpoint

DELETE /v1.0/devices/{device_id}/door-lock/temp-passwords/{password_id}

Request parameter

Parameter	Type	Parameter type	Description	Yes
device_id	String	URI	The device ID.	Yes
password_id	String	URI	The password ID.	Yes

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get a dynamic password

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock

API endpoint

GET /v1.0/devices/{device_id}/door-lock/dynamic-password

Request parameter

Parameter	Type	Parameter type	Description	Yes
device_id	String	URI	The device ID.	Yes

Sample request

GET /v1.0/devices/vdevo153459260090544/door-lock/dynamic-password

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a specified dynamic password.

result

Parameter	Type	Description
dynamic_password	String	A dynamic password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "dynamic_password": ""
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get an offline temporary password

Applicable lock types

• All-in-one Wi-Fi lock
• Bluetooth lock

API endpoint

POST /v1.0/devices/{device_id}/door-lock/offline-temp-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
effective_time	Long	BODY	The 10-digit timestamp of the effective time.	Yes
invalid_time	Long	BODY	The 10-digit timestamp of the expiration time.	Yes
Name	String	BODY	The name of an offline temporary password.	No
type	Int	BODY	The type of password. Valid values: 0: a password that can be used as many times as needed before it expires. 1: a one-time password. 9: a clearing code that clears all passwords. Return a one-time password.	Yes
lang	String	BODY	The language. Set the value to zh for the service deployed in mainland China and set the value to en for the service deployed outside mainland China.	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/offline-temp-password

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a specified dynamic password.

result

Parameter	Type	Description
offline_temp_password	String	An offline temporary password.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "offline_temp_password": ""
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get an offline temporary password v1.1

Note: Compared with v1.0, support for obtaining and clearing a single offline password is added.

Applicable lock types

• All-in-one Wi-Fi lock
• All-in-one Zigbee lock
• All-in-one Bluetooth lock
• Keepalive Wi-Fi locks
• Wi-Fi access control devices

API endpoint

POST: /v1.1/devices/{device_id}/door-lock/offline-temp-password

Request parameter

Parameter	Type	Parameter type	Required	Description
device_id	String	uri	true	The device ID.
offline_pwd_add_request	OfflinePwdAddRequest	body	true	The information about an offline password.

Description of offline_pwd_add_request

Parameter	Type	Required	Description
effective_time	Long	false	The time when a password takes effect. Unit: seconds. 1: Required in case of MULTIPLE(0). 2: ONCE(1)/CLEAR_ALL(9). Take the hour value of the current time. For example, the current time is 2021-01-23 22:11:12, so the value of this field is 2021-01-23 22:00:00. 3: MULTIPLE(0)/CLEAR_ONE(8). Take the hour value of the entered time. For example, the entered time is 2021-01-27 15:11:12, so the final value of this field is 2021-01-27 15:00:00.
invalid_time	Long	false	The time when a password expires. Unit: seconds. 1: Required in case of MULTIPLE(0). 2: ONCE(1). Take the hour value of the current time plus 6 hours. For example, the current time is 2021-01-23 22:11:12, so the value of this field is 2021-01-24 04:00:00. 3: CLEAR_ALL(9). Take the hour value of the current time plus 24 hours. For example, the current time is 2021-01-23 22:11:12, so the value of this field is 2021-01-24 22:00:00. 4: MULTIPLE(0)/CLEAR_ONE(8). Take the hour value of the time if this field is not empty. For example, if the entered time is 2021-01-27 15:11:12, the value of this field is 2021-01-27 15:00:00.
Name	String	false	The password name.
type	String	false	The type of password. multiple: an offline password that can be used for multiple times. once: an offline password that can be used only once. clear_one: clear an offline password. clear_all: clear all offline passwords.
password_id	String	false	The password ID. This value is required when the type is clear_one.

Sample response

Parameter	Type	Description
result	OfflinePwdAddResponse	The result of generating an offline temporary password.

Description of result

Parameter	Type	Description
offline_temp_password_id	String	The password ID.
offline_temp_password	String	The password content.
offline_temp_password_name	String	The password name.
effective_time	Long	The time when a password takes effect. Unit: seconds.
invalid_time	Long	The time when a password expires. Unit: seconds.

Sample request

POST: /v1.1/devices/6cdb36b2e489885fa57lzm/door-lock/offline-temp-password

Sample response

{
    "result": {
        "effective_time": 1623747600,
        "offline_temp_password_id": "2345011",
        "offline_temp_password": "0282554135",
        "invalid_time": 1623769200,
        "offline_temp_password_name": "name267"
    },
    "t": 1623748396631,
    "success": true
}

Update the name of an offline password

Applicable lock types

• All-in-one Bluetooth lock
• Keepalive Wi-Fi locks
• Wi-Fi access control devices

API endpoint

PUT /v1.0/devices/{device_id}/door-lock/offline-temp-password/{password_id}

Request parameter

Parameter	Type	Parameter type	Required	Description
device_id	String	URI	true	The device ID.
password_id	Long	URI	true	The password ID.
password_name	String	BODY	true	The password name.

Sample request

PUT /v1.1/devices/6cdb36b2e489885fa5****/door-lock/offline-temp-password

{
  "passwordName": "new0ne"
}

Response parameter

Parameter	Type	Description
result	boolean	The operation result.

Sample response on success

{
    "success": true,
    "t": 1571898808491,
    "result": true
}

Query unlocking records

Note: This API only applies to legacy versions.

Applicable lock types

• Wi-Fi lock
• Zigbee lock for hotel use
• Bluetooth lock

API endpoint

GET /v1.0/devices/{device_id}/door-lock/open-logs

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
page_no	Integer	URL	The page number.	Yes
page_size	Integer	URL	The number of records returned on each page.	Yes
start_time	Long	URL	The start time.	Yes
end_time	Long	URL	The end time.	Yes

Sample request

GET /v1.0/devices/vdevo153459260090544/door-lock/open-logs?page_no=1&page_size=20&start_time=1543213146&end_time=1543213546

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

result

Parameter	Type	Description
total	Integer	The total number of records.
logs	List	A list of unlocking records.

Description of logs

Parameter	Type	Description
status	List	A list of lock status.
update_time	Long	The time when the status is updated.
unlock_name	String	The name of a specified unlocking method.
user_id	String	The user ID.
nick_name	String	The username.

Description of status

Parameter	Type	Description
Code	String	The status code.
value	Object	The status value.

Description of status codes

Parameter	Type	Description
unlock_fingerprint	Long	Unlock with a fingerprint. The number is assigned locally by the lock.
unlock_password	Long	Unlock with a password. The number is assigned locally by the lock.
unlock_temporary	Long	Unlock with a temporary password. The value is the password ID.
unlock_dynamic	Long	Unlock with a dynamic password. The value is the password ID.
unlock_card	Long	Unlock with a card. The number is assigned locally by the lock.
unlock_face	Long	Unlock with face recognition. The number is assigned locally by the lock.
unlock_key	Long	Unlock with a mechanical key. The number is assigned locally by the lock.
unlock_identity_card	Long	Unlock with an ID card. The number is assigned locally by the lock.
unlock_emergency	Long	Unlock with an emergency password. The number is assigned locally by the lock.

Sample response on success

{
    "success":true,
    "t":1542626129429,
    "result":{
        "total":1,
        "logs":[
            {
                "status":{
                    "code":"unlock_finger",
                    "value":"123456"
                },
		"nick_name":"",
                "unlock_name":"",
                "update_time":1612098422000,
                "user_id":"0"
            }
        ]
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Query the unlocking records

Applicable lock types

• Wi-Fi lock
• Zigbee lock for hotel use
• Bluetooth lock
• Wi-Fi lock with video talk

API endpoint

GET /v1.1/devices/{device_id}/door-lock/open-logs

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
page_no	Integer	URL	The page number.	Yes
page_size	Integer	URL	The number of records returned on each page.	Yes
start_time	Long	URL	The start time.	Yes
end_time	Long	URL	The end time.	Yes
showMediaInfo	Boolean	URL	Indicates whether to display image information.	No

Sample request

GET /v1.1/devices/6cdb36b2e489885fa57lzm/door-lock/open-logs?page_no=1&page_size=3&start_time=1553053133000&end_time=1614008938000&show_media_info=true

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

result

Parameter	Type	Description
total	Integer	The total number of records.
logs	List	A list of unlocking records.

Description of logs

Parameter	Type	Description
status	List	A list of lock status.
update_time	Long	The time when the status is updated.
unlock_name	String	The name of a specified unlocking method.
user_id	String	The user ID.
nick_name	String	The username.
media_infos	List	The media information.

Description of media_infos

Parameter	Type	Description
file_url	String	The full URL of a specified cover image.
file_key	String	The secret key of a specified file.
media_url	String	The full URL of a video.
media_key	String	The secret key of a specified video file.

Description of status

Parameter	Type	Description
Code	String	The status code.
value	Object	The status value.

Description of status codes

Parameter	Type	Description
unlock_fingerprint	Long	Unlock with a fingerprint. The number is assigned locally by the lock.
unlock_password	Long	Unlock with a password. The number is assigned locally by the lock.
unlock_temporary	Long	Unlock with a temporary password. The value is the password ID.
unlock_dynamic	Long	Unlock with a dynamic password. The value is the password ID.
unlock_card	Long	Unlock with a card. The number is assigned locally by the lock.
unlock_face	Long	Unlock with face recognition. The number is assigned locally by the lock.
unlock_key	Long	Unlock with a mechanical key. The number is assigned locally by the lock.
unlock_identity_card	Long	Unlock with an ID card. The number is assigned locally by the lock.
unlock_emergency	Long	Unlock with an emergency password. The number is assigned locally by the lock.

Sample response on success

{
  "result": {
    "logs": [
      {
         "media_infos": [
          {
            "file_key": "uwu5m7kvj45av47g",
            "file_url": "https://..."
          }
        ],
        "nick_name": "",
        "status": {
          "code": "unlock_app",
          "value": "0"
        },
        "unlock_name": "",
        "update_time": 1613978384000,
        "user_id": "0"
      }
    ],
    "total": 1
  },
  "success": true,
  "t": 1614063791358
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get alert records

Note: This API only applies to legacy versions.

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Zigbee lock for hotel use
• Bluetooth lock

API endpoint

GET /v1.0/devices/{device_id}/door-lock/alarm-logs

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
page_no	Integer	URL	The page number.	Yes
page_size	Integer	URL	The number of records returned on each page.	Yes
dp_codes	String	URL	The data point (DP) code of alert features. Separate multiple codes by a comma (,). Common alerts are queried by default.	No

Sample request

GET /v1.0/devices/vdevo153459260090544/door-lock/alarm-logs?page_no=1&page_size=20&dp_codes=hijack

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

result

Parameter	Type	Description
total	Integer	The total number of records.
records	List	A list of alert records.

Description of records

Parameter	Type	Description
status	List	A list of lock alerts.
update_time	Long	The time when the status is updated.
nickName	String	The username.

Description of status

Parameter	Type	Description
Code	String	The DP code of a specified alert.
value	Object	The status value. The value of a duress alarm is the value of the DP set to trigger a duress event.

Sample response on success

{
    "success":true,
    "t":1542626129429,
    "result":{
        "total":1,
        "records":[
            {
                "status":{
                    "code":"hijack",
                    "value":"unlock_fingerprint-02"
                },
                "update_time":1543297979
            }
        ]
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get alert records

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Zigbee lock for hotel use
• Bluetooth lock
• Wi-Fi lock with video talk

API endpoint

GET /v1.1/devices/{device_id}/door-lock/alarm-logs

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
page_no	Integer	URL	The page number.	Yes
page_size	Integer	URL	The number of records returned on each page.	Yes
codes	String	URL	The data point (DP) code of alert features. Separate multiple codes by a comma (,). Common alerts are queried by default.	No
show_media_info	Boolean	URL	Indicates whether to display image information.	No

Sample request

GET /v1.1/devices/6ca87475b5bfbaa716felz/door-lock/alarm-logs?page_size=20&codes=doorbell&showMediaInfo=true&page_no=1

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

result

Parameter	Type	Description
total	Integer	The total number of records.
records	List	A list of alert records.

Description of records

Parameter	Type	Description
status	List	A list of lock alerts.
update_time	Long	The time when the status is updated.
nickName	String	The username.
media_infos	List	The media information.

Description of media_infos

Parameter	Type	Description
file_url	String	The full URL of a specified cover image.
file_key	String	The secret key of a specified file.
media_url	String	The full URL of a video.
media_key	String	The secret key of a specified video file.

Description of status

Parameter	Type	Description
Code	String	The DP code of a specified alert.
value	Object	The status value. The value of a duress alarm is the value of the DP set to trigger a duress event.

Sample response on success

{
    "result": {
        "records": [
            {
                "media_infos": [
                    {
                        "file_key": "jxmgqs59gfr899qe",
                        "file_url": "https://ty-cn-storage60-1254153901.cos.tuyacn.com/"
                    }
                ],
                "nick_name": "",
                "status": [
                    {
                        "code": "alarm_lock",
                        "value": "wrong_password"
                    }
                ],
                "update_time": 1613979671000
            }
        ],
        "total": 1
    },
    "success": true,
    "t": 1614152402757
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get the alert records and unlocking records.

Applicable lock types

• Wi-Fi access control devices

API endpoint

GET /v1.0/devices/{device_id}/door-lock/records

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
target_standard_dp_codes	String	Query	The standard DP codes, separated with commas (,).	Yes
start_time	Long	Query	The start time. The value is 0 when the time range is not required.	Yes
end_time	Long	Query	The end time. The value is 0 when the time range is not required.	Yes
page_no	Integer	Query	The current page number, starting from 1.	Yes
page_size	Integer	Query	The number of records returned on each page.	Yes

Sample request

GET /v1.0/devices/vdevo1623226445*****/door-lock/records?targetStandardDpCodes=unlock_password,unlock_card&startTime=0&endTime=0&pageNo=1&pageSize=10

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

result

Parameter	Type	Description
has_more	Integer	Indicates whether additional data is available.
total_pages	Integer	The total number of pages.
total	Integer	The total number of records.
records	List	The number of records returned on each page.

Description of records

Parameter	Type	Description
record_id	String	The ID of a specified record.
media_info_list	List	The multimedia information, such as a video or image.
union_unlock_info	List	The information about combination unlocking methods.
unlock_name	String	The name of a specified unlocking method.
gmt_create	Long	The time when it was created.
dps	List	The DP data.
avatar	String	The avatar of a specified user.
member_bindable_flag	Integer	Specifies whether the record can be linked with a user. Valid values: 1: Yes. 0: No. Maybe the record is already linked with a user.
user_id	String	The user ID.
user_name	String	The username.
record_type	String	The type of a record. Valid values: alarm: an alert record. normal: a general unlocking record.

Description of media_info_list

Parameter	Type	Description
file_url	String	The full URL of a specified cover image.
file_key	String	The secret key of a specified file.
media_url	String	The full URL of a video.
media_key	String	The secret key of a specified video file.

Description of union_unlock_info

Parameter	Type	Description
user_name	String	The username.
opmode	String	The type of unlocking.
unlock_name	String	The name of a specified unlocking method.

Description of dps

dps is an array where each data is in JSON format. The key refers to dpCode, and the value refers to the value of a specified dpCode.

Sample response on success

{
  "result": {
    "has_more": false,
    "records": [
      {
        "avatar": "https://images.tuyacn.com/smart/user_avatar/ay1565317415087U6QVp/F062FD1C-CA44-440A-9AE5-E270BE4826DD.png?sign=q-sign-algorithm%3Dsha1%26q-ak%3DAKIDopcCYgw0qRoyV5qfKjvg2pPkqESnb5zI%26q-sign-time%3D1624606578%3B1624610178%26q-key-time%3D1624606578%3B1624610178%26q-header-list%3Dhost%26q-url-param-list%3D%26q-signature%3D467422052c41744943fa1c734ed9a44ad2ad7fe1",
        "dps": [
          {
            "unlock_password": "*"
          }
        ],
        "gmt_create": 1624604728299,
        "member_bindable_flag": 0,
        "record_id": "162460b8cfcbb6-d583-11eb-adea-0242878ef26647****",
        "record_type": "alarm",
        "unlock_name": "Password 1",
        "user_id": "3066****",
        "user_name": "James"
      }
    ],
    "total": 1,
    "total_pages": 1
  },
  "success": true,
  "t": 1624606578846
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Link a specified record with a user

Applicable lock types

• Wi-Fi access control devices

API endpoint

POST /v1.0/devices/{device_id}/door-lock/records/{record_id}/actions/allocate

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
record_id	String	URI	The ID of a specified record.	Yes
user_id	String	BODY	The user ID.	Yes

Sample request

POST /v1.0/devices/vdevo16232264458****/door-lock/records/162315AAXEQDzL*****CRCxYNIADC506****/actions/allocate

{
  "userId": 1980012
}

Response parameter

Parameter	Type	Description
result	boolean	The operation result.

Sample response on success

{
    "success": true,
    "t": 1571898808491,
    "result": true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Clear temporary passwords

Applicable lock types

• Zigbee lock for hotel use

API endpoint

POST /v1.0/devices/{device_id}/door-lock/temp-passwords/rest-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/temp-passwords/reset-password

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get the remote unlocking methods supported by a lock

Applicable lock types

• Zigbee lock
• Bluetooth lock

API endpoint

GET /v1.0/devices/{device_id}/door-lock/remote-unlocks

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

GET /v1.0/devices/vdevo153459260090544/door-lock/remote-unlocks

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a specified unlocking command.

result

Parameter	Type	Description
remote_unlock_type	String	The unlocking methods. Valid values: remoteUnlockWithoutPwd: Unlock a door without a password. remoteUnlockWithPwd: Unlock a door with a password.
open	Boolean	Indicates whether a feature is enabled.

Sample response on success

{
    "result": {
        "remote_unlock_type": "remoteUnlockWithPwd",
        "open": true
    },
    "success": true,
    "t": 1592899848757
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Set a switch for a remote unlocking method

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock

API endpoint

POST /v1.0/devices/{device_id}/door-lock/remote-unlock/config

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
remote_unlock_type	String	BODY	The unlocking methods. Valid values: remoteUnlockWithoutPwd: Unlock a door without a password. remoteUnlockWithPwd: Unlock a door with a password.	Yes
open	Boolean	BODY	Indicates whether a feature is enabled.	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/remote-unlock/config

{
    "remote_unlock_type": "remoteUnlockWithPwd",
    "open": true
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful.

Sample response on success

{
    "result": true,
    "success": true,
    "t": 1592899848757
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Unlock with a password

Applicable lock types

• Zigbee lock

API endpoint

POST /v1.0/devices/{device_id}/door-lock/open-door

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password	String	Body	The length of the original password is six digits. The password is encrypted by using the AES-128 algorithm with ECB mode and PKCS7Padding. To get the original key, decrypt the temporary key ticket_key with AES using the accessKey that is issued by the platform.	Yes
password_type	String	BODY	The password is encrypted using a ticket.	Yes
ticket_id	String	BODY	The ID of a specified temporary key.	Yes

Sample request

POST /v1.0/devices/6c362ac3c53fbd6f3ewqfa/door-lock/open-door

Response parameter

Parameter	Type	Description
Code	Integer	The response code. For more information, see the error code section.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

Set an advanced password

Applicable lock types

• Zigbee lock for hotel use

API endpoint

POST /v1.0/devices/{device_id}/door-lock/advanced-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
password	String	Body	The length of the original password is six digits. The password is encrypted by using the AES-128 algorithm with ECB mode and PKCS7Padding. To get the original key, decrypt the temporary key ticket_key with AES using the accessKey that is issued by the platform.	Yes
password_type	String	BODY	The password is encrypted using a ticket.	Yes
ticket_id	String	BODY	The ID of a specified temporary key.	Yes
advanced_type	String	BODY	The type of advanced password. Valid values: admin: administrator password. emergency: emergency password.	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/advanced-password

{
    "password_type":"ticket",
    "password":"7A8F9B6197xxxx7C1D66",
    "ticket_id":"fJeqZd45",
    "advanced_type":"emergency"
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": true
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Query an advanced password

Applicable lock types

Type	Supported
Applicable lock type	Zigbee lock for hotel use

API endpoint

GET /v1.0/devices/{device_id}/door-lock/advanced-password

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
advanced_type	String	URL	The type of advanced password. Valid values: admin: administrator password. emergency: emergency password.	Yes

Sample request

GET /v1.0/devices/vdevo153459260090544/door-lock/advanced-password?advanced_type=admin

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The status of an advanced password.

result

Parameter	Type	Description
advanced_type	String	The type of advanced password. Valid values: admin: administrator password. emergency: emergency password.
phase	Integer	The status of password configuration. Valid values: 1: The password is being configured. 2: Password configuration succeeds. 3: Password configuration fails.

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "advanced_type":"admin",
        "phase":2
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Query video views

Applicable lock types

• Wi-Fi lock

API endpoint

GET /v1.0/smart-lock/devices/{device_id}/media-view-times

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

GET /v1.0/smart-lock/devices/vdevo124546565765/media-view-times

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Integer	The number of video views.

Sample response on success

{
  "result": 1,
  "success": true,
  "t": 1634712882506
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Add one video view

Applicable lock types

• Wi-Fi lock

API endpoint

POST /v1.0/smart-lock/devices/{device_id}/media-view-times

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

POST /v1.0/smart-lock/devices/vdevo124546565765/media-view-times

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Integer	The number of video views.

Sample response on success

{
  "result": 2,
  "success": true,
  "t": 1634713143910
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Remote unlocking with photo capturing

• The following figure shows how remote unlocking with photo capturing works.

  

• Remote unlocking with photo capturing in real time

  • When a user attempts to unlock a door, the camera lock captures a photo and uploads it to the cloud.
  • The cloud stores the media data and sends a relative path to the client.
  • The client calls an API to get the full URL of the media.
  • The client gets the encrypted media data and decrypts it.
  • The user gets the media data and determines whether to unlock the door or revoke permissions to unlock without a password. The APIs will be called accordingly.
  • The cloud sends a command to the lock accordingly.

• Remote unlocking with photo capturing in non-real time

  • The client calls an API to get the unlocking or alert media in the last 90 seconds.
  • The client gets the encrypted media data and decrypts it.
  • The user gets the media data and determines whether to unlock the door or revoke permissions to unlock without a password. The APIs will be called accordingly.
  • The cloud sends a command to the lock accordingly.

The media data is encrypted by using the AES algorithm with CBC mode and PKCS5Padding.

4	16	44	Video content
Placeholder	iv	Placeholder	Video content

The demo shows how decryption works.

package xxxxxxx;

import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;
import java.util.Random;

import javax.crypto.Cipher;
import javax.crypto.CipherInputStream;
import javax.crypto.CipherOutputStream;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;

public class EncryptUtils {

    private static final String DEFAULT_ALGORITHM = "AES";
    private static final String DEFAULT_FULL_ALGORITHM = "AES/CBC/PKCS5Padding";

    // Encryption
    public static File encryptFile(String key, File originFile, String destPath) {
        FileInputStream in = null;
        FileOutputStream out = null;
        File destFile = null;
        try {
            destFile = new File(destPath);
            if (originFile.exists() && originFile.isFile()) {
                if (!destFile.getParentFile().exists()) {
                    destFile.getParentFile().mkdirs();
                }
                destFile.createNewFile();
                in = new FileInputStream(originFile);
                out = new FileOutputStream(destFile, true);
                byte[] iv = getIv();
                Cipher cipher = initAESCipher(iv, key, Cipher.ENCRYPT_MODE);
                CipherInputStream cipherInputStream = new CipherInputStream(in, cipher);
                byte[] cache = new byte[1024];
                int nRead;
                out.write(new byte[4]);
                out.write(iv);
                out.write(new byte[4]);
                out.write(new byte[40]);
                out.flush();
                while ((nRead = cipherInputStream.read(cache)) != -1) {
                    out.write(cache, 0, nRead);
                    out.flush();
                }
                cipherInputStream.close();
            }
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            try {
                if (out != null) {
                    out.close();
                }
                if (in != null) {
                    in.close();
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
        return destFile;
    }

    // Decryption
    public static File decryptFile(String key, InputStream in, File destFile) {
        FileOutputStream out = null;
        try {
            if (!destFile.getParentFile().exists()) {
                destFile.getParentFile().mkdirs();
            }
            destFile.createNewFile();
            out = new FileOutputStream(destFile);
 
            byte[] iv = new byte[16];
            in.skip(4);
            int read = in.read(iv);
            if (read != 16) {
                throw new IOException("iv length error");
            }
            in.skip(44);
            Cipher cipher = initAESCipher(iv, key, Cipher.DECRYPT_MODE);
            CipherOutputStream cipherOutputStream = new CipherOutputStream(out, cipher);
            byte[] buffer = new byte[1024];
            int r;
            while ((r = in.read(buffer)) >= 0) {
                cipherOutputStream.write(buffer, 0, r);
            }
            cipherOutputStream.close();
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            try {
                if (in != null) {
                    in.close();
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
            try {
                if (out != null) {
                    out.close();
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
        return destFile;
    }
 
    private static Cipher initAESCipher(byte[] iv, String sKey, int cipherMode) {
        try {
            IvParameterSpec zeroIv = new IvParameterSpec(iv);
            SecretKeySpec key = new SecretKeySpec(sKey.getBytes(), DEFAULT_ALGORITHM);
            Cipher cipher = Cipher.getInstance(DEFAULT_FULL_ALGORITHM);
            cipher.init(cipherMode, key, zeroIv);
            return cipher;
        } catch (NoSuchAlgorithmException e) {
            e.printStackTrace();
        } catch (NoSuchPaddingException e) {
            e.printStackTrace();
        } catch (InvalidKeyException e) {
            e.printStackTrace();
        } catch (InvalidAlgorithmParameterException e) {
            e.printStackTrace();
        }
        return null;
    }
 
    public static byte[] getIv() {
        StringBuilder uid = new StringBuilder();
        // Generate a 16-digit strong random number.
        Random rd = new SecureRandom();
        for (int i = 0; i < 16; i++) {
            // Generate a 3-digit random number between zero and two.
            int type = rd.nextInt(3);
            switch (type) {
                case 0:
                    // Generate a random number between zero and nine.
                    uid.append(rd.nextInt(10));
                    break;
                case 1:
                    // ASCII between 65 to 90 are randomly capitalized.
                    uid.append((char) (rd.nextInt(25) + 65));
                    break;
                case 2:
                    // ASCII between 97 to 122 are randomly lowercased.
                    uid.append((char) (rd.nextInt(25) + 97));
                    break;
                default:
                    break;
            }
        }
        return uid.toString().getBytes();
    }

}

Unlock without password

Applicable lock types

• All-in-one Wi-Fi lock
• All-in-one Zigbee lock
• Zigbee lock for hotel use
• Bluetooth lock
• Keepalive Wi-Fi locks
• Wi-Fi lock with video talk

API endpoint

POST /v1.0/devices/{device_id}/door-lock/password-free/open-door

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
ticket_id	String	Body	The ID of a specified temporary key.	Yes

Sample request

POST /v1.0/devices/vdevo153459260090544/door-lock/password-free/open-door

{
    "ticket_id":"xxxxx"
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response on success

{
    "result": true,
    "success": true,
    "t": 1592899848757
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Unlock without password (v1.1)

Unlock a specified channel without a password.

Applicable lock types

• Wi-Fi access control devices

API endpoint

POST /v1.1/devices/{device_id}/door-lock/password-free/open-door

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
ticket_id	String	Body	The ID of a specified temporary key. You can get the value through POST:/v1.0/devices/{device_id}/door-lock/password-ticket .	Yes
channel_id	Integer	Body	The channel ID.	Yes

Sample request

POST /v1.1/devices/vdevo15345926009****/door-lock/password-free/open-door

{
    "ticket_id":"WHmutLIq",
    "channel_id":1
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response on success

{
    "result": true,
    "success": true,
    "t": 1592899848757
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Revoke a password-free unlocking

Applicable lock types

Type	Supported
Applicable lock type	Wi-Fi lock

API endpoint

PUT /v1.0/devices/{device_id}/door-lock/password-free/open-door/cancel

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
type	Integer	BODY	The reason to revoke remote unlocking. Valid values: 1: Reject. 2: Cancel.	Yes

Sample request

PUT /v1.0/devices/vdevo153459260090544/door-lock/password-free/open-door/cancel

{
    "type":1
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful.

Sample response on success

{
    "result": true,
    "success": true,
    "t": 1592899848757
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Unlock without password

Applicable lock types

• All-in-one Wi-Fi lock
• All-in-one Zigbee lock
• Zigbee lock for hotel use
• Bluetooth lock
• Keepalive Wi-Fi locks
• Wi-Fi lock with video talk

Note: Remote unlocking requires the DP remote_no_dp_key or remote_no_dp_setkey. Only all-in-one Wi-Fi locks support remote unlocking.

API endpoint

POST /v1.0/smart-lock/devices/{device_id}/password-free/door-operate

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
ticket_id	String	Body	The ID of a specified temporary key.	Yes
open	Boolean	Body	The operation. Valid values: true: Open a door. false: Close a door.	No

Sample request

POST /v1.0/smart-lock/devices/vdevo153459260090544/password-free/door-operate

{
    "ticket_id":"xxxxx",
    "open":false
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response on success

{
    "result": true,
    "success": true,
    "t": 1592899848757
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get a temporary key for password encryption

Note: The temporary key is used to request the API of unlocking without a password.

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock
• Zigbee lock for hotel use
• Wi-Fi lock with video talk

API endpoint

POST /v1.0/smart-lock/devices/{device_id}/password-ticket

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

POST /v1.0/smart-lock/devices/vdevo15345926009****/password-ticket

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a temporary password.

result

Parameter	Type	Description
ticket_id	String	The ID of a specified temporary key.
ticket_key	String	The temporary key. It can be used after decryption with AES using the accessKey that is issued by the platform.
expire_time	Long	The remaining validity period.

Sample response on success

{
    "result": {
        "expire_time": 360,
        "ticket_id": "9wxxoLM",
        "ticket_key": "901CC35A67DA3429C38E9622xxxxx3EAE1CE333462356D257FD1D3E5C"
    },
    "success": true,
    "t": 1592899848757
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get cover image of last remote unlocking or alert

Applicable lock types

• Wi-Fi lock
• Zigbee lock for hotel use
• Bluetooth lock

API endpoint

GET /v1.0/devices/{device_id}/door-lock/latest/media/url

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
file_type	Integer	URL	The file type. Valid values: 1: cover images related to remote unlocking. 2: cover images related to alerts.	Yes

Sample request

GET /v1.0/devices/6cdb36b2e489885fa57lzm/door-lock/latest/media/url?file_type=1

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

result

Parameter	Type	Description
file_url	String	The full URL of a specified cover image.
file_key	String	The key to decrypt a specified file.
bucket	String	The full URL of a specified cover image.
file_path	String	The relative path of a specified file.

Sample response on success

{
    "result": {
        "bucket": "ty-cn-storage60-1254153901",
        "file_key": "u8kstrtjm7qun83q",
        "file_path": "/3039e1-30532026.jpg",
        "file_url": "https://ty-cn-storage60-1254153901.cos.tuyacn.com6"
    },
    "success": true,
    "t": 1614147303662
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Get a list of albums

Applicable lock types

• Wi-Fi lock with video talk

API endpoint

GET /v1.0/smart-lock/devices/{device_id}/albums-media

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

GET /v1.0/smart-lock/devices/vdevo153459260090544/albums-media

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

result

Parameter	Type	Description
eventTypes	array[int]	The types of cover images and videos in a specified album.
albumList	List	A list of albums.
orderCode	Integer	The plan used for the current album query. Valid values: doorlock_cloud_storage_7day: unlimited cloud storage for 7 days. doorlock_cloud_storage_30day: unlimited cloud storage for 30 days. cloud_free_storage_3day: free cloud storage for 3 days.

albumList

Parameter	Type	Description
eventType	int	The file type.
fileUrl	String	The URL of a specified cover image.
fileKey	String	The secret key of a specified cover image.
mediaPath	String	The URL of a specified video file.
mediaKey	String	The secret key of a specified video file.
mediaBucket	String	The repository where the video file is located.
uploadTime	long	The reporting time in seconds.

Description of eventType

Type value	Type	Description
0	int	Anti-pry alert
1	int	Remote unlocking request
2	int	Fingerprint attempt failed
3	int	Password attempt failed
4	int	Card attempt failed
5	int	Face recognition failed
6	int	Palm print recognition failed
7	int	Finger vein recognition failed
8	int	Unlock with fingerprint
9	int	Unlock with password
10	int	Unlock with card
11	int	Unlock with face recognition
12	int	Unlock with palm print
13	int	Unlock with finger vein
14	int	Unlock with temporary password
15	int	Unlock with dynamic password
16	int	Remote unlocking
17	int	Report unlocking with temporary password
18	int	Report doorbell request
19	int	Duress alarm
20	int	Low battery alert
21	int	Mechanical key attempt
22	int	High temperature alert
23	int	Doorbell ringing and remote unlocking
24	int	Loitering alert
25	int	Lock tampering
26	int	Unlock with special fingerprint
27	int	Unlocking in arm mode
28	int	Unlock with remote control

Sample response on success

{
    "success": true,
    "t": 1542626129429,
    "result": {
        "album_list": [
      {
        "event_type": 0,
        "file_id": 109167468,
        "file_key": "76679d2579c74eb7",
        "file_url": "https://ty-cn-storage30-1254153901.cos.tuyacn.com/d76182-35779292-dc706aecd4469145/unify/1630051338.jpeg?sign=q-sign-algorithm%3Dsha1%26q-ak%3DAKIDopcCYgw0qRoyV5qfKjvg2pPkqESnb5zI%26q-sign-time%3D1630137629%3B1630141229%26q-key-time%3D1630137629%3B1630141229%26q-header-list%3Dhost%26q-url-param-list%3D%26q-signature%3D29b40dd6ed4281b78321ec978ce1e56361fd7b57",
        "upload_time": 1630051337
      }
    ],
    "event_types": [
      0
    ],
    "order_code": "cloud_free_storage_3day"
    }
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Device user management

Get a list of home users and unlocking methods

Applicable lock types

• Keepalive Wi-Fi lock
• Wi-Fi lock with video talk

API endpoint

GET /v1.0/smart-lock/devices/{device_id}/users

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
codes	String	URL	The unlocking methods, separated with commas (,). Valid values: unlock_fingerprint: Unlock with fingerprint. unlock_card: Unlock with card. unlock_password: Unlock with password. unlock_face: Unlock with face recognition. unlock_hand: Unlock with palm print. unlock_finger_vein: Unlock with finger vein.	Yes
page_no	int	URI	The current page number, starting from 1.	Yes
page_size	int	URI	The number of records returned per page.	Yes

Sample request

GET /v1.0/smart-lock/devices/vdevo12454656****/users

{
    "codes":"unlock_fingerprint,unlock_password",
    "page_no":1,
    "page_size":100
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	A list of user data.

result

Parameter	Type	Description
user_id	Long	The user ID in a home.
avatar_url	String	The URL of a home user’s avatar.
user_contact	String	The contact information.
unlock_detail	json array	The details of a specified unlocking method.
user_type	int	The user type. Valid values: 10: administrator. 20: common user. 50: home owner.
nick_name	String	The nickname of a specified user.
lock_user_id	int	The user ID on the lock.
back_home_notify_attr	int	Indicates whether to enable notifications of home member arrival. Valid values: 1: yes. 0: no.
effective_flag	int	Indicates whether the current user is within the validity period. Valid values: 1: yes. 0: no.
time_schedule_info	json array	The information about the user’s validity period.
uid	String	The user ID (UID).

unlock_detail

Parameter	Type	Description
dp_code	String	The unlocking method. Valid values: unlock_fingerprint: Unlock with fingerprint. unlock_card: Unlock with card. unlock_password: Unlock with password. unlock_face: Unlock with face recognition. unlock_hand: Unlock with palm print. unlock_finger_vein: Unlock with finger vein.
count	int	The number of the current unlocking methods.
unlock_list	json array	A list of unlocking methods.

unlock_list

Parameter	Type	Description
unlock_id	String	The number of a specified unlocking method in the cloud.
unlock_sn	int	The serial number of a specified unlocking method on the lock.
unlock_name	String	The name of a specified unlocking method.
unlock_attr	int	The attribute of a specified unlocking method. 1: with duress alarm.
op_mode_id	int	The ID of a specified unlocking method in the cloud.
photo_unlock	bool	Indicates whether a lock has the capture feature. This parameter only applies to Wi-Fi locks with the capture feature.
admin	bool	Indicates whether it is the administrator unlocking method on the lock. Notify the cloud through the unlock method synchronization or the reporting of the administrator unlocking method.

time_schedule_info

Parameter	Type	Description
permanent	bool	Indicates whether it is permanently valid. true: permanently valid.
effective_time	String	The effective time in seconds.
expired_time	String	The expiration time in seconds.
operate	String	Recent operations. Valid values: ADD: Add. MODIFY: Modify. DELETE: Delete.
schedule_details	json array	The details of the validity period.

schedule_details

Parameter	Type	Description
start_minute	int	The time when a password becomes effective on that day, in minutes. Maximum value: 1440.
end_minute	int	The time when a password expires on that day, in minutes. Maximum value: 1440.
working_day	Int	The day of the week. Each value accumulates. Valid values: 1: Sunday 2: Monday 4: Tuesday 8: Wednesday 16: Thursday 32: Friday 64: Saturday
time_zone_id	String	The time zone.

Sample response on success

{
  "result": {
    "has_more": false,
    "records": [
      {
        "avatar_url": "https://****",
        "back_home_notify_attr": 0,
        "effective_flag": 1,
        "lock_user_id": 5,
        "nick_name": "Test 1",
        "time_schedule_info": {
          "delivery_status": "SUCCESS",
          "effective_time": 1628179200,
          "expired_time": 1638806399,
          "operate": "MODIFY",
          "permanent": false,
          "schedule_details": [
            {
              "all_day": false,
              "start_minute": 60,
              "end_minute": 480,
              "working_day": 97
            }
          ]
        },
        "uid": "ay1541490670142A1Dti",
        "unlock_detail": [],
        "user_contact": "86-13757150532",
        "user_id": "38823920",
        "user_type": 10
      }
    ],
    "total": 18,
    "total_pages": 1
  },
  "success": true,
  "t": 1628241725953
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Update a user’s validity period

Applicable lock types

• Keepalive Wi-Fi lock
• Wi-Fi access control devices

API endpoint

PUT /v1.0/smart-lock/devices/{device_id}/users/{user_id}/schedule

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
user_id	String	URI	The user ID.	Yes
schedule	json	BODY	The information about the user’s validity period.	Yes

schedule

Parameter	Type	Description
permanent	bool	Indicates whether it is permanently valid. true: permanently valid.
effective_time	String	The effective time in seconds.
expired_time	String	The expiration time in seconds.
schedule_details	json array	The details of the validity period.

schedule_details

Parameter	Type	Description
start_minute	int	The time when a password becomes effective on that day, in minutes. Maximum value: 1440.
end_minute	int	The time when a password expires on that day, in minutes. Maximum value: 1440.
working_day	Int	The day of the week. Each value accumulates. Valid values: 1: Sunday 2: Monday 4: Tuesday 8: Wednesday 16: Thursday 32: Friday 64: Saturday
time_zone_id	String	The time zone.

Sample request

PUT /v1.0/smart-lock/devices/vdevo12454656****/users/130**/schedule

{
  "scheduleDetails": [
    {
      "allDay": false,
      "start_minute": "420",
      "end_minute": "1438",
      "workingDay": 99
    }
  ],
  "effectiveTime": 1628179200,
  "expiredTime": 1640015999,
  "permanent": false
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response on success

{
  "result": true,
  "success": true,
  "t": 1628241725953
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Get a list of unlocking methods applicable to a specified user

Applicable lock types

• Wi-Fi lock with video talk
• Wi-Fi access control devices

API endpoint

GET /v1.0/smart-lock/devices/{device_id}/opmodes/{user_id}

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
user_id	String	URI	The user ID.	Yes
codes	String	URL	The DP codes of the target unlocking methods, separated with commas (,). The value can be empty. unlock_fingerprint: Unlock with fingerprint. unlock_password: Unlock with password. unlock_card: Unlock with card. unlock_face: Unlock with face recognition. unlock_hand: Unlock with palm print. unlock_finger_vein: Unlock with finger vein. unlock_telecontrol_kit: Unlock with a remote control.	Yes
unlock_name	String	URL	The names of the target unlocking methods. The value can be empty.	Yes
page_no	Integer	URL	The current page number, starting from 1.	Yes
page_size	Integer	URL	The number of records returned per page.	Yes

Sample request

GET /v1.0/smart-lock/devices/6c982a30639b8f6338d3ox/opmodes/33970143?page_size=20&page_no=1&codes=unlock_fingerprint,unlock_password,unlock_card&unlock_name=

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

result

Parameter	Type	Description
user_name	String	The username.
user_id	String	The user ID.
user_type	Integer	The user type. Valid values: 0: unknown type. 10: administrator. 20: common home member. 40: shared user. 50: super administrator.
lock_user_id	Integer	The user ID on the lock.
unlock_name	String	The name of a specified unlocking method.
opmode_id	String	The primary key ID of the current unlocking method.
dp_code	String	The DP code of the unlocking method.
unlock_sn	String	The serial number of the unlocking method.
phase	Integer	The status. Valid values: 1: confirmed. 2: to be confirmed. 3: frozen. 4: to be frozen. 5: to be unfrozen. 6: to be reset. 7: failed to create. 8: deleted. 9: to be deleted. 10: to be created.
unlock_attr	Integer	The attribute of a specified unlocking method. 1 indicates the duress attribute.
notify_info	String	The notification method to be returned in the JSON format.
allocate_flag	Boolean	Indicates whether a specified unlocking method has never been allocated to a user before. If yes, it can be unbound. Valid values: 1: yes. 0: no.

notify_info

Parameter	Type	Description
app_send	Integer	Indicates whether to send notifications to the app. Valid values: 0: no. 1: yes. If the notifications are sent through a WeChat public account, the value is also 1.
msg_phone	String	The phone number that receives a message.
voice_phone	String	The phone number that receives a voice notification.

Sample response on success

{
  "result":[
    {
        "phase":3,
        "dp_code":"unlock_password",
        "unlock_attr":0,
        "unlock_name":"lin",
        "user_name": "James",
        "user_id":"28873683",
        "unlock_sn":3,
        "uid":"ay1562298621752U9***",
        "unlock_id":"12-3",
        "operate":"CREATE",
        "lock_user_id":2,
        "opmode_id":"729548",
        "voice_attr":0,
        "user_time_set":"386cd30072bc9b7f000000000000000000",
        "user_type":20,
        "delivery_status":"SUCCESS",
      	"allocate_flag":0,
      	"notify_info":{
            "app_send":1
        }
    },
    {
        "phase":3,
        "dp_code":"unlock_password",
        "unlock_attr":0,
        "unlock_name":"lin-1",
        "user_name": "James",
        "user_id":"28873683",
        "unlock_sn":4,
        "uid":"ay1562298621752U9***",
        "unlock_id":"12-4",
        "operate":"CREATE",
        "lock_user_id":2,
        "opmode_id":"729549",
        "voice_attr":0,
        "user_time_set":"386cd30072bc9b7f000000000000000000",
        "user_type":20,
        "delivery_status":"SUCCESS",
        "allocate_flag":1,
      	"notify_info":{
            "app_send":0,
            "msg_phone":"86-15156789943"
        }
    }
]
  "sucess":ture,
  "t":1542626129429
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Get a list of removed users

Applicable lock types

• Wi-Fi lock with video talk

API endpoint

GET /v1.0/devices/{device_id}/door-lock/absent-users

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

GET /v1.0/devices/6c982a30639b8f6338d3ox/door-lock/absent-users

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

result

Parameter	Type	Description
user_id	String	The user ID.
user_type	Integer	The user type. Valid values: 50: super administrator. 10: administrator. 20: common user. 40: shared member. 0: unknown user.
lock_user_id	Integer	The user ID on the lock.

Sample response on success

{
  "result": [
{
      "user_id": "390981",
      "user_type": 10,
      "lock_user_id": 2
    }
],
  "success": true,
  "t": 1628241725953
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Delete the information about users.

Applicable lock types

• Wi-Fi lock with video talk

API endpoint

POST /v1.0/smart-lock/devices/{device_id}/users/{user_ids}/actions/delete-users-issue

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
user_ids	String	URI	A list of user IDs, separated with commas (,).	Yes

Sample request

POST /v1.0/smart-lock/devices/6c982a30639b8f6338****/users/xxx/actions/delete-users-issue

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response on success

{
  "result": true,
  "success": true,
  "t": 1628241725953
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Add a device user

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock

API endpoint

POST /v1.0/devices/{device_id}/user

Request parameter

Parameter	Parameter type	Description	Required
device_id	String	The device ID.	Yes
nick_name	String	The username.	Yes
sex	Integer	Gender. Valid values: 1: male. 2: female.	Yes
birthday	Long	The date of birth (day, month, year).	No
height	Integer	The height (cm).	No
weight	Integer	The weight (g).	No
contact	String	The contact information.	No

Response parameter

Name	Type	Description
t	Long	The returned time.
success	Boolean	Indicates whether the operation is successful.
result	Object	The returned result.

Description of result

Name	Type	Description
user_id	String	The added user ID.

Modify a device user

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock

API endpoint

PUT /v1.0/devices/{device_id}/users/{user_id}

Request parameter

Parameter	Parameter type	Description	Required
device_id	String	The device ID.	Yes
user_id	String	The added user ID.	Yes
nick_name	String	The username.	Yes
sex	Integer	Gender. Valid values: 1: male. 2: female.	Yes
birthday	Long	The date of birth (day, month, year).	No
height	Integer	The height (cm).	No
weight	Integer	The weight (g).	No

Response parameter

Name	Type	Description
t	Long	The timestamp.
success	Boolean	Indicates whether the operation is successful.
result	Object	The returned result.

Update the role of a device user

Applicable lock types

• Wi-Fi access control devices

API endpoint

PUT /v1.0/smart-lock/devices/{device_id}/users/{user_id}/actions/role

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
user_id	String	URI	The user ID.	Yes
role	String	BODY	The new role. Valid values: admin: administrator. normal: common user.	Yes

Sample request

PUT /v1.0/smart-lock/devices/6c5fa86feedc16f77d****/users/8923iu****/actions/role

{
    "role": "admin"
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.

Sample response on success

{
  "success": true,
  "t": 1614147303662
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Delete a device user

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock

API endpoint

DELETE /v1.0/devices/{device_id}/users/{user_id}

Request parameter

Parameter	Parameter type	Description	Required
device_id	String	The device ID.	Yes
user_id	String	The user ID.	Yes

Response parameter

Name	Type	Description
t	Long	The timestamp.
success	Boolean	Indicates whether the operation is successful.
result	Object	The returned result.

Query device user information

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock

Note: You cannot query the administrators.

API endpoint

GET /v1.0/devices/{device_id}/users/{user_id}

Request parameter

Parameter	Parameter type	Description	Required
device_id	String	The device ID.	Yes
user_id	String	The user ID.	Yes

Response parameter

Parameter	Parameter type	Description
device_id	String	The device ID.
nick_name	String	The username.
sex	Integer	Gender. Valid values: 1: male. 2: female.
birthday	Long	The date of birth (day, month, year).
height	Integer	The height (cm).
weight	Integer	The weight (g).
contact	String	The contact information.

Query device user information (v1.1)

Query the information about the current user. You cannot query the administrators.

Applicable lock types

• Wi-Fi access control devices

API endpoint

GET /v1.1/devices/{device_id}/users/{user_id}

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
user_id	String	URI	The user ID. Set the value to 0 to query the information about the current user.	Yes

Sample request

GET /v1.1/devices/vdevo16232264458****/users/0

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter	Type	Description
user_id	String	The user ID.
avatar_url	String	The URL of an avatar.
user_contact	String	The contact information.
user_type	Integer	The user type. Valid values: 10: administrator. 20: common user. 50: home owner.
nick_name	String	The nickname of a specified user.
lock_user_id	Integer	The user ID on the lock.
back_home_notify_attr	Integer	Indicates whether to enable notifications of home member arrival. Valid values: 1: yes. 0: no.
effective_flag	Integer	Indicates whether a specified user is valid. A valid user is currently managed within the validity period. Valid values: 1: yes. 0: no.
time_schedule_info	Object	The information about the user’s validity period.
uid	String	The user ID (UID).

Description of time_schedule_info

Parameter	Type	Description
permanent	Boolean	Specifies whether the user is a permanent user.
effective_time	Long	The effective time in seconds.
expired_time	Long	The expiration time in seconds.
operate	String	The operation type. Valid values: ADD: Add. MODIFY: Modify. DELETE: Delete.
delivery_status	String	The operation feedback from the device. Valid values: ONGOING: The password is being sent. SUCCESS: The password is successfully sent. FAILED: Failed to send the password.
schedule_details	List	The details of the validity period.

Description of schedule_details

Parameter	Type	Description
start_minute	Long	The effective time, which is stored in minutes. For example, 07:30 indicates that the value is 450. Calculation: 7 x 60 + 30 = 450.
end_minute	Long	The expiration time, which is stored in minutes. For example, 17:30 indicates that the value is 1050. Calculation: 17 x 60 + 30 = 1050.
working_day	Integer	The day of the week. Each value accumulates. Valid values: 1: Sunday 2: Monday 4: Tuesday 8: Wednesday 16: Thursday 32: Friday 64: Saturday
all_day	Boolean	Indicates whether the password is valid all the day.
time_zone_id	String	The time zone ID. Example: Asia/Shanghai.

Sample response on success

{
  "result": {
    "avatar_url": "https://thirdwx.qlogo.cn/mmopen/vi_32/y6E5GpvgQicwyxjCkJfpNcBo5Sd6wtmYbjHY6kzyibEn9yNicmGDZWrc0BxaaC2xFPibh5k9niaRMjGTEuNFZPFsP3g/132",
    "lock_user_id": 1,
    "nick_name": "Alan",
    "user_contact": "",
    "user_id": "38028607",
    "user_type": 50
  },
  "success": true,
  "t": 1632448688665
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Query user list by device ID

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock

API endpoint

GET /v1.0/devices/{device_id}/users

Request parameter

Parameter	Parameter type	Description	Required
device_id	String	The device ID.	Yes

Response parameter

Parameter	Parameter type	Description
device_id	String	The device ID.
nick_name	String	The username.
sex	Integer	The gender. Valid values: 1: male. 2: female.
birthday	Long	The date of birth (day, month, year).
height	Integer	The height (cm).
weight	Integer	The weight (g).
contact	String	The contact information.

Query user list by device ID (v1.1)

Note: Compared with v1.0, this API supports data filtering based on the keyword and role information.

Applicable lock types

• Wi-Fi access control devices

API endpoint

GET /v1.1/devices/{device_id}/users

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
keyword	String	Query	The query keyword. Currently, data is returned only based on the username and account. Fuzzy matching is supported. When the value is an empty string, it is not used to filter data.	Yes
role	String	Query	The role. If the value is an empty string, it is not used to filter data. admin: administrator. normal: common user.	Yes
page_no	Integer	Query	The current page number, starting from 1.	Yes
page_size	Integer	Query	The number of records returned per page.	Yes

Sample request

GET /v1.1/devices/vdevo16232264458****/users?keyword=test&role=admin&page_no=1&page_size=10

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter	Type	Description
has_more	Boolean	Indicates whether additional data is available.
total_pages	Integer	The total number of pages.
total	Integer	The total number of records.
records	List	The number of records returned on each page.

Description of records

Parameter	Type	Description
user_id	String	The user ID.
avatar_url	String	The URL of an avatar.
user_contact	String	The contact information.
user_type	Integer	The user type. Valid values: 10: administrator. 20: common user. 50: home owner.
nick_name	String	The nickname of a specified user.
lock_user_id	Integer	The user ID on the lock.
back_home_notify_attr	Integer	Indicates whether to enable notifications of home member arrival. Valid values: 1: yes. 0: no.
effective_flag	Integer	Indicates whether a specified user is valid. A valid user is currently managed within the validity period. Valid values: 1: yes. 0: no.
time_schedule_info	Object	The information about the user’s validity period.
uid	String	The user ID (UID).

Description of time_schedule_info

Parameter	Type	Description
permanent	Boolean	Specifies whether the user is a permanent user.
effective_time	Long	The effective time in seconds.
expired_time	Long	The expiration time in seconds.
operate	String	The operation type. Valid values: ADD: Add a password. MODIFY: Modify a password. DELETE: Delete a password.
delivery_status	String	The operation feedback from the device. Valid values: ONGOING: The password is being sent. SUCCESS: The password is successfully sent. FAILED: Failed to send the password.
schedule_details	List	The details of the validity period.

Description of schedule_details

Parameter	Type	Description
start_minute	Long	The effective time, which is stored in minutes. For example, 07:30 indicates that the value is 450. Calculation: 7 x 60 + 30 = 450.
end_minute	Long	The expiration time, which is stored in minutes. For example, 17:30 indicates that the value is 1050. Calculation: 17 x 60 + 30 = 1050.
working_day	Integer	The day of the week. Each value accumulates. Valid values: 1: Sunday 2: Monday 4: Tuesday 8: Wednesday 16: Thursday 32: Friday 64: Saturday
all_day	Boolean	Indicates whether the password is valid all the day.
time_zone_id	String	The time zone ID. Example: Asia/Shanghai.

Sample response on success

{
  "result": {
    "has_more": true,
    "records": [
      {
        "avatar_url": "",
        "back_home_notify_attr": 0,
        "effective_flag": 1,
        "lock_user_id": 1,
        "nick_name": "Nicole",
        "time_schedule_info": {
          "permanent": true
        },
        "user_contact": "test@163.com",
        "user_id": "30665363",
        "user_type": 50,
        "uid": "ay1***6168*****VdmWA"
      }
    ],
    "total": 14,
    "total_pages": 14
  },
  "success": true,
  "t": 1624613523063
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Assign a password to a device user

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock

API endpoint

POST /v1.0/devices/{device_id}/device-lock/users/{user_id}/allocate

Request parameter

Parameter	Type	Description	Required
device_id	String	The device ID.	Yes
user_id	String	The ID of a specified device user.	Yes
no	String	The serial number of a specified lock.	Yes
type	String	The unlocking type, including fingerprint, password, and card.	Yes

Response parameter

Parameter	Type	Description
result	boolean	The operation result.

Sample response on success

{
    "success": true,
    "t": 1571898808491,
    "result": true
}

Assign multiple unlocking methods to users

Applicable lock types

• Wi-Fi access control devices
• Bluetooth lock

API endpoint

POST /v1.0/devices/{device_id}/door-lock/opmodes/actions/allocate

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	URI	String	The device ID.	Yes
user_id	BODY	String	The user ID.	Yes
unlock_list	BODY	List	A list of unlocking methods.	Yes

Description of unlock_list

Parameter	Type	Description	Required
dp_code	String	The standard DP code of a specified unlocking method.	Yes
unlock_sn	Integer	The serial number of the unlocking method.	Yes

Sample request

POST /v1.0/devices/vdevo16232264458****/door-lock/opmodes/actions/allocate

{
  "user_id": "30665363",
  "unlock_list": [
    {
      "dp_code": "unlock_password",
      "unlock_sn": 2
    }
  ]
}

Response parameter

Parameter	Type	Description
result	boolean	The operation result.

Sample response on success

{
    "success": true,
    "t": 1571898808491,
    "result": true
}

Get devices linked with a user account

Applicable lock types

• Wi-Fi access control devices

API endpoint

GET /v1.0/smart-lock/users/{uid}/devices

Request parameter

Parameter	Type	Parameter type	Description	Required
uid	String	URI	The device ID.	Yes
page_no	Integer	Query	The current page number, starting from 1.	Yes
page_size	Integer	Query	The channel ID.	The number of records returned per page.

Sample request

GET /v1.0/smart-lock/users/bay1629701943556****/devices?page_no=1&page_size=10

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter	Type	Description
total	Integer	The total number of items.
total_pages	Integer	The total number of pages.
has_more	Boolean	Indicates whether additional data is available.
records	List	The number of records returned on each page.

Description of records

Parameter	Type	Description
id	String	The device ID.
uuid	String	The universally unique identifier (UUID) of a specified device.
uid	String	The user ID (UID).
Name	String	The device name.
time_zone	String	The time zone.
ip	String	The IP address of a specified device.
local_key	String	The secret key.
sub	Boolean	Determines whether it is a sub-device.
model	String	The product model.
active_time	Long	The time when the device was last paired.
lon	String	The longitude.
lat	String	The latitude.
owner_id	String	The ID of the home that a device belongs to.
product_id	String	The product ID.
product_name	String	The product name.
category	String	The product category.
icon	String	The device icon.
online	Boolean	Indicates whether the device is online.

Sample response on success

{
  "result": {
    "has_more": false,
    "records": [
      {
        "active_time": 1626252626,
        "category": "ldcg",
        "icon": "smart/program_category_icon/ldcg.png",
        "id": "6c8d95e9b2d8cfe1a*****",
        "ip": "",
        "lat": "",
        "local_key": "dc1ba7ed034****c",
        "lon": "",
        "model": "S-LUX-ZB",
        "name": "Light Sensor",
        "online": true,
        "product_id": "pisltm67",
        "product_name": "Luminance Sensor",
        "sub": true,
        "time_zone": "+08:00",
        "uuid": "6c8d9*****d8cfe1a****"
      }
    ],
    "total": 2,
    "total_pages": 1
  },
  "success": true,
  "t": 1632462436318
}

Sample response on failure

{
    "success": false,
    "code": 500, // The error code. For more information, see Global Error Codes.
    "msg": "system error, please contact the admin"
}

Unlocking method APIs

Flowchart

Get a list of linked unlocking methods

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock
• Wi-Fi lock with video talk (home user only)

API endpoint

GET /v1.0/devices/{device_id}/door-lock/user-types/{user_type}/users/{user_id}/assigned-keys

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
user_type	Integer	URI	The user type. Valid values: 1: home user. 2: not a home user.	Yes
user_id	String	URI	The user ID.	Yes
unlock_type	String	URL	The unlocking type, including fingerprint, password, and card.	No

Sample request

GET /v1.0/devices/xxx/door-lock/user-types/2/users/xxx/assigned-keys?unlock_type=card

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a specified unlocking method.

result

Parameter	Type	Description
unlock_keys	List	A list of unlocking methods.

Description of unlock_keys

Parameter	Type	Description
unlock_no	Integer	The ID of a specified unlocking method. That is the flag of each unlocking method such as password, fingerprint, and card.
unlock_type	String	The unlocking type, including fingerprint, password, and card.
hijack	Boolean	Indicates whether the duress alarm feature is enabled.

Sample response on success

{
    "result":{
        "unlock_keys":[
            {
                "unlock_no":3,
                "unlock_type":"card",
                "hijack":false
            }
        ]
    },
    "success":true,
    "t":1593843316481
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Get unlinked unlocking methods

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock
• Wi-Fi access control devices

API endpoint

GET /v1.0/devices/{device_id}/door-lock/unassigned-keys

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
unlock_type	String	URL	The unlocking type, including fingerprint, password, card, and remote control.	No

Sample request

GET /v1.0/devices/xxxx/door-lock/unassigned-keys?unlock_type=card

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The information about a specified unlocking method.

result

Parameter	Type	Description
unlock_keys	List	A list of unlocking methods.

Description of unlock_keys

Parameter	Type	Description
unlock_no	Integer	The ID of a specified unlocking method. That is the flag of each unlocking method such as password, fingerprint, and card.
unlock_type	String	The unlocking type, including fingerprint, password, and card.

Sample response on success

{
    "result":{
        "unlock_keys":[
            {
                "unlock_no":3,
                "unlock_type":"card"
            }
        ]
    },
    "success":true,
    "t":1593843316481
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Sync unlocking methods by the cloud

Applicable lock types

• Bluetooth lock with gateway
• Keepalive Wi-Fi lock
• Wi-Fi lock with video talk
• Wi-Fi access control devices

API endpoint

POST /v1.0/smart-lock/devices/{device_id}/opmodes/actions/sync

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
codes	String	URL	The unlocking methods, separated with commas (,). Valid values: unlock_fingerprint: Unlock with fingerprint. unlock_card: Unlock with card. unlock_password: Unlock with password. unlock_face: Unlock with face recognition. unlock_hand: Unlock with palm print. unlock_finger_vein: Unlock with finger vein. unlock_telecontrol_kit: Unlock with a remote control.	Yes

Sample request

PUT /v1.0/smart-lock/devices/vdevo12454656****/opmodes/actions/sync

{
    "codes":"unlock_fingerprint,unlock_password"
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.

Sample response on success

{
    "result":true,
    "success":true,
    "t":1593843316481
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Enroll in unlocking methods

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock
• Keepalive Wi-Fi lock (home user only)
• Wi-Fi lock with video talk (home user only)
• Wi-Fi access control devices

API endpoint

PUT /v1.0/devices/{device_id}/door-lock/actions/entry

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
user_id	String	BODY	The user ID.	Yes
user_type	Integer	BODY	The user type. Valid values: 1: home user. 2: not a home user. Select this type for a Wi-Fi lock.	Yes
unlock_type	String	BODY	The type of a specified unlocking method. Valid values: fingerprint: Unlock with fingerprint. password: Unlock with password. card: Unlock with card. face:Unlock with face recognition. remoteControl: Unlock with remote control.	Yes
password_type	String	BODY	The password encryption type. The password is encrypted by using a ticket. It is available only when the device is the Bluetooth door locks and unlock_type is password.	No
ticket_id	String	BODY	The temporary key ID for password encryption. It is available only when the device is the Bluetooth door locks and unlock_type is password.	No
password	String	BODY	The password. It is available only when the device is the Bluetooth door locks and unlock_type is password.	No

Sample request

PUT /v1.0/devices/xxx/door-lock/actions/entry

{
    "unlock_type":"card",
	"user_type":2,
    "user_id":"000xxxwsn"
}

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.

Sample response on success

{
    "result":true,
    "success":true,
    "t":1593843316481
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Delete an unlocking method

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock
• Keepalive Wi-Fi lock (home user only)
• Wi-Fi access control devices

API endpoint

DELETE /v1.0/devices/{device_id}/door-lock/user-types/{user_type}/users/{user_id}/unlock-types/{unlock_type}/keys/{unlock_no}

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
user_type	Integer	URI	The user type. Valid values: 1: home user. 2: not a home user. Select this type for a Wi-Fi lock.	Yes
user_id	String	URI	The user ID.	Yes
unlock_type	String	URI	The unlocking type, including fingerprint, password, card, and remote control.	Yes
unlock_no	Integer	URI	The ID of a specified unlocking method. That is the flag of each unlocking method such as password, fingerprint, and card.	Yes

Sample request

DELETE /v1.0/devices/xxxx/door-lock/user-types/2/users/xxxx/unlock-types/fingerprint/keys/30

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.

Sample response on success

{
    "result":true,
    "success":true,
    "t":1593843316481
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Cancel unlocking method enrollment

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock
• Keepalive Wi-Fi lock (home user only)
• Wi-Fi lock with video talk (home user only)
• Wi-Fi lock with video talk (home user only)
• Wi-Fi access control devices

API endpoint

PUT /v1.0/devices/{device_id}/door-lock/unlock-types/{unlock_type}/actions/cancel

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
unlock_type	String	URI	The unlocking type, including fingerprint, password, card, and remote control.	Yes

Sample request

PUT /v1.0/devices/xxx/door-lock/unlock-types/card/actions/cancel

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.

Sample response on success

{
    "result":true,
    "success":true,
    "t":1593843316481
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Update the name of an unlocking method

Applicable lock types

• Wi-Fi access control devices

API endpoint

PUT /v1.0/devices/{device_id}/door-lock/opmodes/{unlock_sn}

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
unlock_sn	Integer	URI	The serial number of the unlocking method.	Yes
dp_code	String	BODY	The standard DP code of a specified unlocking method. Valid values: unlock_password: Unlock with password. unlock_fingerprint: Unlock with fingerprint. unlock_card: Unlock with card. unlock_face: Unlock with face recognition. unlock_telecontrol_kit: Unlock with a remote control.	Yes
unlock_name	String	BODY	The name of a specified unlocking method.	Yes

Sample request

PUT  /v1.0/devices/vdevo16232264458****/door-lock/opmodes/2

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	Indicates whether the operation is successful. true: succeeded. false: failed.

Sample response on success

{
    "result":true,
    "success":true,
    "t":1593843316481
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Set an unlocking method to trigger a duress alarm

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock

API endpoint

PUT /v1.0/devices/{device_id}/door-lock/unlock-types/{unlock_type}/keys/{unlock_no}/hijack

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
unlock_type	String	URI	The unlocking type, including fingerprint, password, and card.	Yes
unlock_no	Integer	URI	The ID of a specified unlocking method. That is the flag of each unlocking method such as password, fingerprint, and card.	Yes

Sample request

PUT /v1.0/devices/xxx/door-lock/unlock-types/card/keys/130/hijack

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	Indicates whether the operation is successful. true: succeeded. false: failed.

Sample response on success

{
    "result":true,
    "success":true,
    "t":1593843316481
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Delete the duress alarm of unlocking methods

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock

API endpoint

DELETE /v1.0/smart-lock/devices/{device_id}/unlock-types/{unlock_type}/keys/{unlock_sn}/hijack

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
unlock_type	String	URI	The unlocking method. Valid values: unlock_fingerprint: Unlock with fingerprint. unlock_card: Unlock with card. unlock_password: Unlock with password.	Yes
unlock_sn	Integer	URI	The ID of a specified unlocking method. That is the flag of each unlocking method such as password, fingerprint, and card.	Yes

Sample request

DELETE /v1.0/smart-lock/devices/vdevo12454656****/unlock-types/unlock_fingerprint/keys/1/hijack

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	Indicates whether the operation is successful. true: succeeded. false: failed.

Sample response on success

{
    "result":true,
    "success":true,
    "t":1593843316481
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Set special attributes

Applicable lock types

• Wi-Fi lock

API endpoint

POST /v1.0/smart-lock/devices/{device_id}/opmodes/{opmode_id}/attribute/{attribute}/opmode-attr

Request parameter

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
opmode_id	Long	URI	The serial number of a specified unlocking method.	Yes
attribute	Integer	URI	The attribute. Valid values: 1: voice attribute. 2: photo capturing attribute.	Yes
enabled	Boolean	BODY	Specifies whether to enable this feature. true: enable. false: disable.	Yes

Sample request

POST /v1.0/smart-lock/devices/vdevo12454656****/opnodes/1234/attribute/4/opmode-attr

Response parameter

Parameter	Type	Description
Code	Integer	The error code that is returned if the API call fails. This parameter value is empty if the API call succeeds.
success	Boolean	Indicates whether the operation is successful. true: succeeded. false: failed.
t	Long	The response time.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	Indicates whether the operation is successful. true: succeeded. false: failed.

Sample response on success

{
    "result":true,
    "success":true,
    "t":1593843316481
}

Sample response on failure

{
    "success":false,
    "code":500, // The error code. For more information, see Global Error Codes.
    "msg":"system error, please contact the admin"
}

Common commands to control locks

• Standard Instruction Set for Smart Locks
• Device Control

Push notification of unlocking method enrollment results

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock

Parameters

Parameter	Type	Description
bizCode	String	The code of a specified event type.
devId	String	The device ID.
uuid	Integer	The universally unique identifier (UUID) of a specified device.
bizData	Object	The status of a specified unlocking method.
ts	Long	The timestamp.

bizCode

bizCode	Description
doorUnlockMethodStatus	The status of a specified unlocking method.

bizData

Code	Data type	Description
finish	Boolean	Indicates whether unlocking method enrollment is completed.
operate	Integer	The operation. Valid values: 1: Initiate unlocking method enrollment. 2: Cancel unlocking method enrollment.
raised	Boolean	Indicates whether an unlocking method enrollment is initiated.
totalPeriod	Integer	The total number of enrollments. The value will be pushed separately and only once.
period	Integer	The number of remaining enrollments allowed for users.
event	String	The event, including unlockMethodEntry and unlockMethodDelete.

Data format****

{
    "bizCode":"doorUnlockMethodStatus",
    "bizData":{
        "finish":false,
        "operate":1,
        "raised":true,
        "totalPeriod":2,
        "period":2,
        "event":"unlockMethodEntry"
    },
    "uuid":"xxxx",
    "devId":"xxxx"
}

Get device details

API description

You can query the device details, including attributes and the latest status of a specified device.

API endpoint

GET /v1.0/devices/{device_id}

Request parameter

Parameter	Type	Parameter type	Required	Description
device_id	String	URI	Yes	The device ID.

Response parameter

Parameter	Type	Description
Code	Integer	The response code. See Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The error message returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object<result>	The returned result.

Description of result

Parameter	Type	Description
id	String	The device number.
Name	String	The device name.
uid	String	The user ID.
local_key	String	The secret key.
category	String	The product category.
product_id	String	The product ID.
product_name	String	The product name.
sub	Boolean	Determines whether it is a sub-device. Valid values: true: yes false: no
uuid	String	The universally unique identifier (UUID) of a specified device.
owner_id	String	The home ID.
online	Boolean	The online status of a specified device.
status	Object<status>	The status of a specified device feature.
active_time	Long	The time when a specified device is activated, which is accurate to seconds.
biz_type	Long	The biztype of a specified application.
icon	String	The device icon.
ip	String	The IP address of a specified device.

Description of status

Parameter	Type	Description
Code	String	The code of a specified data point.
value	String	The value of a specified data point.
type	String	The type of a specified data point.

Sample request

GET /v1.0/devices/vdevo153490924188132

Sample SDK

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
DeviceVo deviceVo = client.getDeviceInfo(DEV_ID);
System.out.println("Get device details: ");
System.out.println(JSONObject.toJSONString(deviceVo));

Sample response

{
    "success": true,
    "result": {
        "active_time": 1589505938,
        "biz_type": 299009,
        "category": "qt",
        "create_time": 1560827137,
        "icon": "smart/icon/15402589135gknz23xajb_0.png",
        "id": "60613135b121cddc294****",
        "ip": "120.198.****.****",
        "local_key": "3a9b50126fe473****",
        "name": "Body fat scale",
        "online": true,
        "owner_id": "1070****",
        "product_id": "g0er6hSKgMqr****",
        "product_name": "Wifi scales_OEM",
        "status": [
            {
                "code": "weight",
                "value": "48900"
            },
            {
                "code": "left_hand_r",
                "value": "0"
            },
            {
                "code": "right_hand_r",
                "value": "0"
            },
            {
                "code": "left_leg_r",
                "value": "0"
            },
            {
                "code": "right_leg_r",
                "value": "0"
            },
            {
                "code": "body_r",
                "value": "653"
            },
            {
                "code": "battery_low",
                "value": "false"
            }
        ],
        "sub": false,
        "time_zone": "+08:00",
        "uid": "ay157896239864843g****",
        "update_time": 1589764585,
        "uuid": "60613135b23cddc294****"
    }
}

Error codes

The following table lists common error codes returned in the API calls. For more error codes, see Global Error Codes.

Error code	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.