Unenroll a device

Tool Name: airdroid_business_unenroll_device

Risk Level: 🔴 High Risk

Execution Mode: ⚡ Synchronous

Category: Security Operations

Quick Start (Copy & Use)

Summary: Remove a device from the organization's enrollment (device will be unenrolled from MDM management — this is an irreversible operation)

Prerequisites: DeviceId (device identifier) + Confirm=true + Reason (reason for the operation)

Success Criteria: StatusCode=200 and ErrorMessage=""

What to Do Next: The device is now unenrolled from management. To re-manage it, physical access to the device is required for re-enrollment.

Minimal Request Example:

{
  "DeviceId": "abc123def456",
  "Confirm": true,
  "Reason": "Device no longer in use, removing from organization"
}

Minimal Response Example:

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

Recipes (Common Recipes)

Recipe 1: Remove a Retired Device

Scenario: An employee has left the company or a device is being decommissioned — remove it from the organization.

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Confirm": true,
  "Reason": "Employee departure, device returned and removed from organization"
}

Recipe 2: Remove a Lost Device

Scenario: A device is lost and cannot be recovered — remove it from organizational management.

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Confirm": true,
  "Reason": "Device lost and unrecoverable, removing from organization"
}

Recipe 3: Remove Old Device Before Replacement

Scenario: Replacing a device for a user — first remove the old device enrollment.

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Confirm": true,
  "Reason": "Device replacement, removing old device enrollment for user to use new device"
}

1. Overview

1.1 Description

Remove a device from the AirDroid Business organization enrollment. After execution, the device will be unenrolled from MDM management and can no longer receive remote commands or policy deployments.

1.2 When to Use

• Employee departure: Remove device enrollment after an employee leaves and returns the device
• Device decommission: Clean up device records when a device is retired or scrapped
• Device lost: Remove management for a device that is lost and cannot be recovered
• Device replacement: Remove old device enrollment before assigning a replacement device to a user

1.3 Execution Mode and Response

This operation is synchronous — results are returned immediately after the call.

• Response: StatusCode and ErrorMessage
• No tracking needed: Synchronous operation, no Pid returned
• Device status: The device does not need to be online — enrollment for offline devices will also be removed

1.4 Prerequisites

1.5 Prerequisite Tools

1.6 Differences from Similar Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`DeviceId`

Device unique identifier, specifying the target device to unenroll.

• Type: string
• Format: Non-empty device ID string
• Source:

How to obtain:

1. Via Get All Devices tool — use the device_id field from the response
2. Via Get a Device by Name tool — look up by exact device name

The device_id field in the output can be directly used as this parameter.

• How to fill in GI node:
  • Constant: Enter the device ID string directly, e.g., fa6edcff65ab444e8b5e0eb08df4175d
  • Upstream reference: Use Devices[0].device_id from the Get All Devices node output
• Example:

  "fa6edcff65ab444e8b5e0eb08df4175d"

`Confirm`

Safety confirmation flag. This is a guardrail parameter for high-risk operations, preventing accidental execution of destructive actions.

• Type: bool
• Default: false (will not execute)
• Must be set to true to execute: If false, the operation will be rejected with an error
• How to fill in GI node:
  • Constant: Set to true (only after user has explicitly confirmed)
• Example:

  true

⚠️ Important: The agent must ask the user for confirmation before calling this tool. Only set this parameter to true after receiving explicit user approval.

`Reason`

Reason for the operation, used for audit trail and compliance logging.

• Type: string
• Format: Non-empty string; recommended to include specific reason and context
• Purpose: Recorded in the activity log for subsequent auditing and issue tracking
• How to fill in GI node:
  • Constant: Enter a specific reason description
  • Upstream reference: Obtain from user input or workflow context
• Example:

  "Employee departure, device returned and removed from organization"

⚠️ Important: The Reason parameter must be provided by the user. The agent should not fabricate reasons.

2.3 Parameter Combination Logic

• Confirm + Reason: Together they form the guardrail mechanism
  • Confirm=false: Operation will not execute, returns error message
  • Confirm=true but Reason is empty: Operation will not execute, returns error message
  • Confirm=true and Reason is non-empty: Operation executes normally

3. Outputs

3.1 Response Examples

Success Response:

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

Parameter Validation Failure Response:

{
  "StatusCode": -1,
  "ErrorMessage": "Invalid device_id. Obtain via 'Get All Devices' or 'Get a Device by Name' tool."
}

Unconfirmed Operation Response:

{
  "StatusCode": 200,
  "ErrorMessage": "Confirm must be set to true to execute this destructive operation."
}

Missing Reason Response:

{
  "StatusCode": 200,
  "ErrorMessage": "Reason is required for audit trail."
}

Business Error Response (upstream HTTP error):

{
  "StatusCode": 200,
  "ErrorMessage": "API returned HTTP 404: {\"code\":0,\"msg\":\"Device not found\"}"
}

Network Error Response:

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

3.2 Field Descriptions

3.3 Status Code / Enum Value Mapping

4. Examples

4.1 Basic Example: Remove Device After Employee Departure

Scenario: An employee has left and returned their device — remove the device enrollment from the organization.

Request Parameters:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Confirm": true,
  "Reason": "Employee John left the company, device returned and removed from organization"
}

Response:

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

4.2 Advanced Example: Look Up Device Then Unenroll

Scenario: Only the device name is known — first look up the device ID, then unenroll.

Step 1: Call Get a Device by Name to get device information

{
  "DeviceName": "Sales-Tablet-001"
}

Response (simplified):

{
  "Device": {
    "device_id": "fa6edcff65ab444e8b5e0eb08df4175d",
    "device_name": "Sales-Tablet-001"
  }
}

Step 2: Ask user for confirmation first, then call Unenroll a Device

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Confirm": true,
  "Reason": "Device Sales-Tablet-001 no longer in use, removing from organization"
}

4.3 Error Example: User Confirmation Not Obtained

Scenario: Attempting to execute the operation but Confirm parameter is false.

Request Parameters:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Confirm": false,
  "Reason": "Test operation"
}

Response:

{
  "StatusCode": 200,
  "ErrorMessage": "Confirm must be set to true to execute this destructive operation."
}

4.4 Error Example: Device Not Found

Request Parameters:

{
  "DeviceId": "invalid_device_id",
  "Confirm": true,
  "Reason": "Remove device"
}

Response:

{
  "StatusCode": 200,
  "ErrorMessage": "API returned HTTP 404: {\"code\":0,\"msg\":\"Device not found\"}"
}

5. Error Handling

5.1 AB Three-Layer Error Codes

Core Principle: AB uses a three-layer error code strategy. The agent should decide handling based on StatusCode.

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Optimization

• Confirm device exists: Use Get All Devices before executing to confirm the device exists
• Batch operation considerations: If removing multiple devices, consider using batch interfaces (if available)

6.2 Security Considerations

⚠️ High-Risk Operation Warning: This operation will cause the device to leave MDM management. Re-enrolling requires physical access to the device.

⚠️ Special Warning — Android Enterprise Devices:

Devices enrolled through Android Enterprise (including Zero-Touch and Samsung Knox Mobile Enrollment (KME)) may be factory reset after unenrollment.

Pre-Execution Checklist:

1. ☐ Confirm the target device is correct (verify device ID and device name)
2. ☐ Understand the enrollment method (whether enrolled via Android Enterprise)
3. ☐ Notify the device holder (inform them the device will leave management)
4. ☐ Back up necessary data (especially for Android Enterprise devices that may be factory reset)
5. ☐ Obtain explicit user confirmation (agent must ask user first)
6. ☐ Understand the irreversibility (re-management requires physical access to the device)

6.3 Idempotency

Idempotency of this operation: Not idempotent

• First call: Removes device enrollment, returns success
• Second call (same device ID): Device no longer exists, may return 404 error

Note: Do not blindly retry this operation due to timeouts. If unsure whether it succeeded, use Get All Devices to check if the device still exists.

6.4 Re-Enrollment Instructions

After a device is unenrolled, if it needs to be managed again:

1. Physical access to the device: Someone must operate the device on-site
2. Reinstall/configure MDM client: Re-set up according to the organization's enrollment method
3. Android Enterprise devices: May need to go through the factory setup process again

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tool Comparison

8. Tool Chains

8.1 Employee Departure Device Recovery Flow

Scenario: An employee is leaving — securely recover and remove device management.

Tool Chain:

Get a Device by Name → (Optional) Lock a Device → Unenroll a Device → Get All Devices (confirm removal)

Steps:

1. Call Get a Device by Name to get the departing employee's device device_id
2. (Optional) Call Lock a Device to lock the device and prevent data leakage
3. After physically recovering the device, ask user for confirmation
4. Call Unenroll a Device to remove device enrollment
5. Call Get All Devices to confirm the device has been removed from the organization

8.2 Device Decommission Flow

Scenario: A device is being retired — clean it from the organization.

Tool Chain:

Get All Devices (identify target devices) → Factory Reset (optional) → Unenroll a Device

Steps:

1. Call Get All Devices to get the list of devices to be decommissioned
2. (Optional) Call Factory Reset to wipe device data
3. Ask user for confirmation, then call Unenroll a Device to remove device enrollment
4. The device can be physically destroyed or recycled

8.3 Lost Device Handling Flow

Scenario: A device is lost and cannot be recovered — remove it from the organization.

Tool Chain:

Get a Device by Name → Enable Lost Mode → (wait for recovery) → Unenroll a Device

Steps:

1. Call Get a Device by Name to get lost device information
2. Call Enable Lost Mode to activate lost mode (lock and display contact information)
3. If the device still cannot be recovered after some time, ask user for confirmation
4. Call Unenroll a Device to remove the device from the organization

Appendix Reference:

• Field Reference: https://www.goinsight.ai/tools/field-reference/
• Error Code Quick Reference: https://www.goinsight.ai/tools/error-codes/