Lock a device

Tool Name: airdroid_business_lock_device

Risk Level: 🟠 Medium Risk

Execution Mode: ⏳ Asynchronous

Category: Remote Commands

Quick Start (Copy & Use)

One-liner: Remotely lock a device screen with an optional password

What you need: DeviceId (device ID), Pwd (optional, 6-digit numeric password)

Success criteria: StatusCode = 200 and ErrorMessage is an empty string; returns Pid for tracking

What to do next: Use Get an Activity Log with the Pid to poll execution status

Minimal request example:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d"
}

Request with password example:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Pwd": "123456"
}

Minimal response example:

{
  "Pid": "1770854462319857000",
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Lock screen only (no password)

Scenario: Temporarily lock the device screen; the device already has an existing lock password

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d"
}

Recipe 2: Lock and set a new password

Scenario: Device is lost; immediately lock and set a password for protection

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Pwd": "123456"
}

⚠️ Note: If the device already has a password, providing a new one will overwrite the existing password.

Recipe 3: Track lock status with Pid

Scenario: After locking, confirm whether the device was successfully locked

1. Call Lock a Device to get the Pid
2. Use the Get an Activity Log tool to query status:

{
  "Pid": "1770854462319857000"
}

Polling logic:

• Progress = "Executing" → continue polling (interval 5-10 seconds)
• Progress = "Success" → lock succeeded
• Progress = "Failure" → check the FailReason field

1. Overview

1.1 Description

Remotely lock the screen of a device managed by AirDroid Business. Optionally set a 6-digit numeric password. Applicable to scenarios such as device loss, security protection, or temporary lockdown.

1.2 When to Use

• Lost device protection: Immediately lock a lost device to prevent data leakage
• Security hardening: Remotely set a lock screen password for devices without one
• Temporary lockdown: Temporarily disable device usage (e.g. during employee offboarding transitions)

1.3 Execution Mode & Response

This operation is asynchronous — after the command is sent, the device may take a few seconds to respond.

• Return value: Pid (activity log ID)
• Tracking method: Use the Get an Activity Log tool with the Pid to query execution status
• Prerequisite: The device must be online to receive the command
• Typical duration: Usually completes within 3-10 seconds

1.4 Prerequisites

1.5 Prerequisite Tools

1.6 Comparison with Similar Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`DeviceId`

Device unique identifier.

• Type: string
• Format: Non-empty string
• Source:
  1. Obtained via the Get All Devices tool; use the device_id field from the response
  2. Obtained via the Get a Device by Name tool for exact name lookup
• How to fill in a GI node:
  • Constant: Enter the device ID string directly, e.g. fa6edcff65ab444e8b5e0eb08df4175d
  • Upstream reference: Map from the Get All Devices node's Devices[0].device_id field
• Example:

  "fa6edcff65ab444e8b5e0eb08df4175d"

`Pwd`

Optional 6-digit numeric lock screen password.

• Type: string
• Format: Must be exactly 6 digits (regex: ^\d{6}$)
• Behavior:
  • No password provided: Only locks the screen; uses the device's existing password (if any)
  • Password provided + device has no password: Sets this as the lock screen password
  • Password provided + device already has a password: Overwrites the existing password
  • No password provided + device has no password: Operation may fail
• How to fill in a GI node:
  • Constant: e.g. "123456"
  • Leave empty: Omit or leave blank to skip setting a password
• Example:

  "123456"

⚠️ Important: Providing a password will overwrite the device's existing password. Use with caution.

2.3 Parameter Combination Logic

• DeviceId is required; Pwd is optional
• If the device has no lock screen password and Pwd is not provided, the lock operation may fail
• Recommendation: For devices without a password, always provide the Pwd parameter

3. Outputs

3.1 Response Examples

Success response:

{
  "Pid": "1770854462319857000",
  "StatusCode": 200,
  "ErrorMessage": ""
}

Parameter error response:

{
  "Pid": "",
  "StatusCode": 200,
  "ErrorMessage": "Invalid device_id."
}

Network error response:

{
  "Pid": "",
  "StatusCode": 500,
  "ErrorMessage": "Request timeout after 60 seconds."
}

3.2 Field Descriptions

3.3 Pid Tracking

Use the returned Pid with the Get an Activity Log tool to track execution status:

4. Examples

4.1 Basic Example: Lock screen only

Request:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d"
}

Response:

{
  "Pid": "789012",
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.2 Advanced Example: Lock and set password

Request:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Pwd": "654321"
}

Response:

{
  "Pid": "789013",
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.3 Error Example: Invalid password format

Request:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Pwd": "12345"
}

Response:

{
  "Pid": "",
  "StatusCode": 200,
  "ErrorMessage": "Invalid pwd, must be a string."
}

Note: The password must be exactly 6 digits.

5. Error Handling

5.1 AB Three-Layer Error Codes

Core principle: AB uses a three-layer error code strategy. The agent should decide how to handle based on StatusCode.

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Tips

• Confirm device is online: Check device status before locking to avoid sending commands to offline devices
• Prefer existing password: If the device already has a password, there is no need to set one again

6.2 Security Considerations

⚠️ Medium Risk Warning: This operation locks the device screen, which may affect users currently using the device.

Side effects:

• If the device has no lock screen password, providing Pwd will set a password
• If the device already has a lock screen password, providing Pwd will overwrite the existing password

Pre-execution checklist:

1. ☐ Confirm the device is online
2. ☐ Confirm the correct target device (avoid locking the wrong device)
3. ☐ Confirm whether a password needs to be set or changed
4. ☐ Record the new password (if set)

6.3 Idempotency

Idempotency: Conditionally idempotent.

• Re-locking an already locked device will refresh the lock state
• If Pwd is provided, each call updates the password
• Without Pwd, multiple calls produce the same result

6.4 Async Operation Tracking

Use the returned Pid with Get an Activity Log to track execution status:

Polling recommendations:

• Interval: 5-10 seconds
• Max polling attempts: 6 (approx. 30-60 seconds)
• On timeout: Prompt the user to manually check device status

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tools Comparison

8. Tool Chains

8.1 Lost Device Emergency Response

Scenario: Device is lost; needs immediate lock for protection

Tool chain:

Get a Device by Name → Lock a Device (with password) → Get an Activity Log

Steps:

1. Call Get a Device by Name to query the lost device's device_id
2. Call Lock a Device to send the lock command and set a password
3. Use Get an Activity Log with the Pid to confirm lock success

8.2 Batch Lock Pattern

Scenario: Lock company devices after business hours

Tool chain:

Get All Devices (filter target group) → [Loop] Lock a Device → Get an Activity Log

Steps:

1. Call Get All Devices with Keyword={"group_name":"office-devices"} to get the target device list
2. Iterate through devices and call Lock a Device for each
3. Collect all Pid values and use Get an Activity Log to batch-track status

8.3 Escalate to Lost Mode

Scenario: After locking, the device is still not recovered; enable full lost mode

Tool chain:

Lock a Device → (wait) → Enable Lost Mode

Steps:

1. Call Lock a Device to immediately lock the device
2. If the device is not recovered, call Enable Lost Mode to enable lost mode (display custom message, enable location tracking)