Smart Lock Open APIs

Last Updated on : 2023-06-20 14:53:58download

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.

Smart Lock Open APIs

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.

    Smart Lock Open APIs

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

    Smart Lock Open APIs

    • 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

Smart Lock Open APIs

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://airtake-public-data-1254153901.cos.ap-shanghai.myqcloud.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.

    Smart Lock Open APIs

  • 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

    Smart Lock Open APIs

    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

    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.