Tuya.com
English
简体中文
Register
Developer Platform
English
简体中文
Register
Developer Platform
Cloud Services API Reference
search
Search By Document Directory
Cloud Services API ReferenceAdvanced Device ServicesExtension APIsSmart Lock Open APIsUnlocking & Alert History APIs

Unlocking & Alert History APIs

Last Updated on : 2024-06-26 09:22:07download

Query unlocking history (legacy)

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 parameters

Parameter name 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 maximum number of items 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 parameters

Parameter name 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 API call is successful. Valid values:
  • true: success.
  • false: failure.
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 name Type Description
total Integer The total number of returned items.
logs List A list of unlocking history.

Description of logs

Parameter name 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 the specified unlocking method.
user_id String The user ID.
nick_name String The username.

Description of status

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

Description of status codes

Parameter name Type Description
unlock_fingerprint Long Unlock with a fingerprint. The value is a number assigned by the lock.
unlock_password Long Unlock with a password. The value is a number assigned 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 an access card. The value is a number assigned by the lock.
unlock_face Long Unlock with face recognition. The value is a number assigned by the lock.
unlock_key Long Unlock with a mechanical key. The value is a number assigned by the lock.
unlock_identity_card Long Unlock with an identity card. The value is a number assigned by the lock.
unlock_emergency Long Unlock with an emergency password. The value is a number assigned 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 unlocking history (new)

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 parameters

Parameter name 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 maximum number of items 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 parameters

Parameter name 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 API call is successful. Valid values:
  • true: success.
  • false: failure.
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 name Type Description
total Integer The total number of returned items.
logs List A list of unlocking history.

Description of logs

Parameter name 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 the 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 name Type Description
file_url String The full URL of the specified cover image.
file_key String The secret key of the specified file.
media_url String The full URL of the specified video file.
media_key String The secret key of the specified video file.

Description of status

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

Description of status codes

Parameter name Type Description
unlock_fingerprint Long Unlock with a fingerprint. The value is a number assigned by the lock.
unlock_password Long Unlock with a password. The value is a number assigned 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 an access card. The value is a number assigned by the lock.
unlock_face Long Unlock with face recognition. The value is a number assigned by the lock.
unlock_key Long Unlock with a mechanical key. The value is a number assigned by the lock.
unlock_identity_card Long Unlock with an identity card. The value is a number assigned by the lock.
unlock_emergency Long Unlock with an emergency password. The value is a number assigned 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 history (legacy)

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 parameters

Parameter name 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 maximum number of items returned on each page. Yes
dp_codes String URL The data point (DP) codes of alert features, separated with commas (,). 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 parameters

Parameter name Type Description
code Integer The response code. This parameter value is empty if the API call succeeds. For more information, see the error codes.
success Boolean Indicates whether the API call is successful. Valid values:
  • true: success.
  • false: failure.
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 name Type Description
total Integer The total number of returned items.
records List A list of alert history.

Description of records

Parameter name 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 name Type Description
code String The standard code of the specified alert.
value Object The status value. The value of a duress alarm is the value of the standard status code 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 history (new)

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 parameters

Parameter name 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 maximum number of items returned on each page. Yes
dp_codes String URL The data point (DP) codes of alert features, separated with commas (,). 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 parameters

Parameter name Type Description
code Integer The response code. This parameter value is empty if the API call succeeds. For more information, see the error codes.
success Boolean Indicates whether the API call is successful. Valid values:
  • true: success.
  • false: failure.
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 name Type Description
total Integer The total number of returned items.
records List A list of alert history.

Description of records

Parameter name 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 name Type Description
file_url String The full URL of the specified cover image.
file_key String The secret key of the specified file.
media_url String The full URL of the specified video file.
media_key String The secret key of the specified video file.

Description of status

Parameter name Type Description
code String The standard code of the specified alert.
value Object The status value. The value of a duress alarm is the value of the standard status code 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 alert and unlocking history

Applicable lock types

  • Wi-Fi access control devices

API endpoint

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

Request parameters

Parameter name Type Parameter type Description Required
device_id String URI The device ID. Yes
target_standard_dp_codes String QUERY One or more standard functions to be queried, specified by dpCode. Multiple values are 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 items 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 parameters

Parameter name Type Description
code Integer The response code. This parameter value is empty if the API call succeeds. For more information, see the error codes.
success Boolean Indicates whether the API call is successful. Valid values:
  • true: success.
  • false: failure.
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 name 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 returned items.
records List The list of data on pages.

Description of records

Parameter name Type Description
record_id String The ID of the specified history.
media_info_list List The multimedia information, such as a video or image.
union_unlock_info List The information about combined unlocking methods.
unlock_name String The name of the specified unlocking method.
gmt_create Long The creation time.
dps List The information about the specified data point.
avatar String The avatar of the specified user.
member_bindable_flag Integer Indicates whether the history can be linked with a user. Valid values:
  • 1: yes.
  • 0: no. Maybe the history is already linked with a user.
user_id String The user ID.
user_name String The username.
record_type String The type of the specified history. Valid values:
  • alarm: an alert history.
  • normal: a general unlocking history.

Description of media_info_list

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

Description of union_unlock_info

Parameter name Type Description
user_name String The username.
opmode String The type of unlocking.
unlock_name String The name of the 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 the specified dpCode.

Sample response on success

{
  "result": {
    "has_more": false,
    "records": [
      {
        "avatar": "https://images.tuyacn.com/smart/user_avatar/ay1565317415087U6QVp/F062FD1C-CA44-440A-9AE5-E270BE4826DD.png?sign=q-sign-algorithm%3Dsha1%26q-ak%3DAKIDopcCYgw0qRoyV5qfKjvg2pPkqESnb5zI%26q-sign-time%3D1624606578%3B1624610178%26q-key-time%3D1624606578%3B1624610178%26q-header-list%3Dhost%26q-url-param-list%3D%26q-signature%3D467422052c41744943fa1c734ed9a44ad2ad7***",
        "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 history 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 parameters

Parameter name Type Parameter type Description Required
device_id String URI The device ID. Yes
record_id String URI The ID of the specified history. 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 parameters

Parameters 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"
}
Prev DocPassword Management APIs
Next DocUser Management API
Language
English
English
简体中文
844-672-5646
7×24 Service Hotline
Marketing Cooperation
marketing@tuya.com
Business Cooperation
vip@tuya.com
Customer Service
service@tuya.com
Media Inquiry
pr@tuya.com
Contact UsTuyaExpoApp MallTuyaGo
Privacy PolicyTerms of UseCalifornia Privacy NoticeBug BountyDo Not Sell or Share My Information
© 2025 Tuya Inc.
English
English
简体中文