Unlocking method APIs

Last Updated on : 2023-06-15 05:15:16

Unlocking method 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"
}

Prev DocUser Management API

Next DocDoorlock Photos & Video API