Get a device by name

Tool Name: airdroid_business_get_device_by_name

Risk Level: 🟢 Low Risk

Execution Mode: ⚡ Synchronous

Category: Device Management

Quick Start (Copy & Use)

Summary: Retrieve a single device's detailed information by exact name match (case-insensitive).

Prerequisites: DeviceName (device name, required) + optional SelectedColumns (control returned fields).

Success Criteria: StatusCode == 200 and ErrorMessage == ""; a non-empty Device object means the device was found, an empty object {} means not found.

What to Do Next: Use Device.device_id as input for subsequent device operations (e.g., Reboot Device, Lock a Device).

Minimal Request Example (recommended to copy directly):

{
  "DeviceName": "Test Device 01"
}

Minimal Response Example (device exists):

{
  "Device": {
    "device_id": "abc123def456ghi789jkl012mno345pq",
    "device_name": "Test Device 01",
    "note": ""
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Response when device does not exist:

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

Recipes (Common Recipes)

Recipe 1: Minimal Call (Device Name Only)

When to use: You only need to get the device's device_id for subsequent operations.

{
  "DeviceName": "NYC-POS-001"
}

Recipe 2: Get Device Status Information

When to use: You need to view the device's online status, battery, network, and other operational info.

{
  "DeviceName": "NYC-POS-001",
  "SelectedColumns": ["device_id", "device_name", "online", "battery", "network_type", "ip", "group_name"]
}

Recipe 3: Get Device Hardware Identifiers

When to use: You need to get the device's IMEI, MAC address, serial number, and other hardware identifiers.

{
  "DeviceName": "Warehouse-Scanner-A1",
  "SelectedColumns": ["device_id", "device_name", "snid", "imei", "mac", "eth_mac", "model", "manu"]
}

Recipe 4: Get Device Location Information

When to use: You need to view the device's GPS location information.

{
  "DeviceName": "Delivery-Tablet-05",
  "SelectedColumns": ["device_id", "device_name", "lng", "lat", "acc", "position_update_time"]
}

1. Overview

1.1 Description

Retrieve a single device's detailed information by exact name match. Uses the Filter API's eq operator for matching, with case-insensitive exact matching.

1.2 When to Use

• Known device name query: When you already know the device name and need to get the device's device_id or other details
• Pre-query for single device operations: Before performing Reboot Device, Lock a Device, etc., get the target device's ID first
• Device existence verification: Verify whether a device with a specific name exists in the system

1.3 Execution Mode and Response

This operation is synchronous and returns results immediately after the call.

• Return values:
  • Device: Device information object (when found) or empty object {} (when not found)
  • StatusCode: Status code
  • ErrorMessage: Error message (empty string on success)

1.4 Prerequisites

1.5 Prerequisite Tools

1.6 Differences from Similar Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`DeviceName`

• Type: string
• Required: Yes
• Format: String, the complete device name
• Matching rule: Exact match, case-insensitive. For example, "Test Device 01" can match "test device 01" or "TEST DEVICE 01"
• Source:
  1. From business systems (e.g., asset management, deployment manifests)
  2. Query via Get All Devices to get the device_name field
• How to fill in GI node:
  • Constant: Enter the device name string directly, e.g., "NYC-POS-001"
  • Upstream reference: Get device name from upstream node (ensure it is the complete name)
• Example:

"Test Device 01"

Important: If the device name does not exist, the tool returns an empty object {} instead of an error. Check whether Device is empty to determine if the device was found.

`SelectedColumns`

• Type: string-array
• Required: No
• Default: ["device_name","device_id","note"]
• Format: String array (list of field names)
• Available values (commonly used fields):
  • Core fields: device_id, device_name, online, battery, group_name, group_id
  • Device info: model, manu, os_version, snid, platform_type
  • Network info: network_type, ip, private_ip, mac, eth_mac, signal_strength
  • Identifiers: imei, imei2, imsi, imsi2, android_id, iccid1, iccid2
  • Status info: cpu_usage, available_rom, battery_source, batterycharging, am_state, daemon_status, config_status, lost_mode_status
  • Location info: lng, lat, acc, position_update_time
  • Metadata: tags, note, bind_date, last_connect_date
• How to fill in GI node:
  • Constant: Provide an array directly, e.g., ["device_id","device_name","online","battery"]
  • Upstream reference: If upstream output is already an array type, map it directly
• Example:

["device_id", "device_name", "online", "battery", "group_name", "ip"]

Why recommended: The default returns only 3 fields. If you need other information (e.g., online status, battery), you must explicitly specify them.

2.3 Parameter Combination Logic

• DeviceName is required for exact device matching
• SelectedColumns controls which fields are returned, does not affect matching logic
• It is recommended to always include device_id and device_name for subsequent operations and confirmation

3. Outputs

3.1 Response Example

Success response (device exists):

{
  "Device": {
    "device_id": "abc123def456ghi789jkl012mno345pq",
    "device_name": "Test Device 01",
    "note": ""
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Success response (device does not exist):

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

Error response (invalid credential):

{
  "Device": {},
  "StatusCode": -1,
  "ErrorMessage": "access_token is invalid."
}

3.2 Field Descriptions

3.3 Status Code / Enum Value Mapping

3.4 Determining Whether Device Was Found

Since the tool does not return an error when the device is not found (StatusCode remains 200), you need to check the Device object:

Agent decision logic example:

IF StatusCode == 200 AND ErrorMessage == "" THEN
    IF Device.device_id EXISTS THEN
        // Device found, proceed with subsequent operations
    ELSE
        // Device does not exist, prompt user to check device name
    END IF
END IF

4. Examples

4.1 Basic Example: Query by Device Name

Request Parameters:

{
  "DeviceName": "Test Device 01"
}

Response:

{
  "Device": {
    "device_id": "abc123def456ghi789jkl012mno345pq",
    "device_name": "Test Device 01",
    "note": ""
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.2 Advanced Example: Get Full Device Status

Request Parameters:

{
  "DeviceName": "NYC-POS-001",
  "SelectedColumns": [
    "device_id",
    "device_name",
    "online",
    "battery",
    "network_type",
    "ip",
    "private_ip",
    "group_name",
    "model",
    "os_version",
    "last_connect_date"
  ]
}

Response:

{
  "Device": {
    "device_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "device_name": "NYC-POS-001",
    "online": "Online",
    "battery": 85,
    "network_type": "Wi-Fi",
    "ip": "123.45.67.89",
    "private_ip": "192.168.1.100",
    "group_name": "Manhattan Store",
    "model": "Samsung Galaxy Tab A",
    "os_version": "11",
    "last_connect_date": "2026-02-04 10:30:00"
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.3 Error Example: Device Name Does Not Exist

Request Parameters:

{
  "DeviceName": "Non-Existent-Device"
}

Response:

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

Note: When the device does not exist, StatusCode is still 200. Determine whether the device was found by checking if Device is an empty object.

4.4 Error Example: Missing Required Parameter

Request Parameters (error - missing DeviceName):

{
  "SelectedColumns": ["device_id", "device_name"]
}

Response:

{
  "Device": {},
  "StatusCode": -1,
  "ErrorMessage": "DeviceName is required."
}

5. Error Handling

5.1 AB Three-Layer Error Codes

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

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Optimization

• Specify SelectedColumns as needed: Only retrieve the fields you need to reduce response size
• Ensure device name accuracy: Exact match returns results quickly, avoiding unnecessary queries

6.2 Security Considerations

🟢 Read operation: No special security requirements.

Returned fields may contain sensitive information (e.g., IMEI, phone numbers, location). Recommendations:

• Do not retrieve sensitive fields by default
• Only add them to SelectedColumns when business requires it

6.3 Idempotency

Idempotency: Naturally idempotent.

This is a read operation; multiple calls return the same result (when device info has not changed). However, device status is dynamic, so repeated calls with the same parameters may yield different results due to status changes.

6.4 Device Name Matching

• Matching method: Exact match, case-insensitive
• Example: Querying "Test Device 01" can match a device named "test device 01" or "TEST DEVICE 01"
• Note: Fuzzy matching or wildcards are not supported. For fuzzy queries, use Get All Devices with Keyword filtering

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tool Comparison

8. Tool Chains

8.1 Execute Remote Operation by Device Name

Scenario: You know the device name and need to reboot the device.

Tool Chain:

Get a Device by Name → Reboot Device → Get an Activity Log

Steps:

1. Call Get a Device by Name:
   • DeviceName="NYC-POS-001"
   • SelectedColumns=["device_id","device_name","online"]
2. Check if Device exists and online="Online"
3. Use Device.device_id to call Reboot Device
4. Use the returned Pid to call Get an Activity Log to track execution status

8.2 Device Verification and Update

Scenario: Verify if a device exists; if so, update the device name.

Tool Chain:

Get a Device by Name → Update a Device Name

Steps:

1. Call Get a Device by Name to get device info
2. Check if Device exists (non-empty object)
3. If it exists, use Device.device_id to call Update a Device Name

8.3 Get Device Location with Refresh

Scenario: You need to get the device's real-time location information.

Tool Chain:

Get a Device by Name → Get Device Info Push → Get a Device by Name

Steps:

1. Call Get a Device by Name to get device_id
2. Use device_id to call Get Device Info Push to trigger the device to report latest status
3. Wait a few seconds, then call Get a Device by Name again to get the latest location info (SelectedColumns including lng, lat, position_update_time)

Appendix Reference:

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