User Management API

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 a password. MODIFY: Modify a password. DELETE: Delete a password.
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	Return the 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	Return the 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	Return the 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	Return the 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	The 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	The 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

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	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 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	Return the 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 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": {
    "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)

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.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	Return the 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 value: 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
}

Unbind Multiple Unlocking Methods from Users

Applicable lock types

• Wi-Fi lock
• Zigbee lock
• Bluetooth lock (only unbind the unlocking methods that can be unbound through API calls)

API endpoint

POST /v1.0/smart-lock/devices/{device_id}/opmodes/actions/cancel-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
Code	String	The code of a specified unlocking method. Valid values: 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_eye: Unlock with iris recognition.	Yes
unlock_sn	int	The serial number of the unlocking method.	Yes

Sample request

POST /v1.0/smart-lock/devices/vdevo16232264458****/opmodes/actions/cancel-allocate

{
  "user_id": "00****pdo",
  "unlock_list": [
    {
      "dp_code": "unlock_fingerprint",
      "unlock_sn": 2
    },
    {
      "dp_code": "unlock_password",
      "unlock_sn": 1
    },
    {
      "dp_code": "unlock_card",
      "unlock_sn": 3
    }
  ]
}

Response parameter

Parameter	Type	Description
result	boolean	The operation result.

Sample response on success

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

Get the devices linked with a specified 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"
}

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.