Unlock & Alarm Records API

Unlock & Alarm Records API

Query unlocking records

Note: This API only applies to legacy versions.

Applicable lock types

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

API endpoint

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

Request parameter

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

Sample request

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

Response parameter

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

result

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

Description of logs

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

Description of status

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

Description of status codes

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

Sample response on success

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

Sample response on failure

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

Query the unlocking records

Applicable lock types

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

API endpoint

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

Request parameter

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

Sample request

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

Response parameter

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

result

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

Description of logs

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

Description of media_infos

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

Description of status

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

Description of status codes

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

Sample response on success

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

Sample response on failure

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

Get alert records

Note: This API only applies to legacy versions.

Applicable lock types

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

API endpoint

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

Request parameter

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

Sample request

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

Response parameter

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

result

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

Description of records

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

Description of status

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

Sample response on success

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

Sample response on failure

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

Get alert records

Applicable lock types

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

API endpoint

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

Request parameter

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

Sample request

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

Response parameter

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

result

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

Description of records

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

Description of media_infos

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

Description of status

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

Sample response on success

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

Sample response on failure

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

Get the alert records and unlocking records.

Applicable lock types

• Wi-Fi access control devices

API endpoint

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

Request parameter

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

Sample request

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

Response parameter

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

result

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

Description of records

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

Description of media_info_list

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

Description of union_unlock_info

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

Description of dps

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

Sample response on success

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

Sample response on failure

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

Link a specified record with a user

Applicable lock types

• Wi-Fi access control devices

API endpoint

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

Request parameter

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

Sample request

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

{
  "userId": 1980012
}

Response parameter

Parameter	Type	Description
result	boolean	The operation result.

Sample response on success

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

Sample response on failure

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