Unlocking method APIs

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

Unlocking method APIs

Flowchart

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