Get tag ids by tag names

Tool Name: airdroid_business_get_tag_ids_by_tag_names

Risk Level: 🟢 Low Risk

Execution Mode: ⚡ Synchronous

Category: Device Management

Quick Start (Copy & Use)

Summary: Look up tag IDs by tag names in batch.

Prerequisites: TagNames (array of tag name strings).

Success Criteria: StatusCode == 200 and ErrorMessage is empty string.

What to Do Next: Use the retrieved tag IDs to call Set Tags to assign tags to devices.

Minimal Request Example:

{
  "TagNames": ["Sales Department", "New York Office"]
}

Minimal Response Example:

{
  "TagIds": {
    "found": {
      "Sales Department": 108
    },
    "not_found": ["New York Office"]
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Look Up a Single Tag ID

When to use: You need to get the ID for a single tag.

{
  "TagNames": ["Sales Department"]
}

Recipe 2: Batch Look Up Multiple Tag IDs

When to use: You need to get IDs for multiple tags at once.

{
  "TagNames": ["Sales Department", "Marketing", "IT Support", "VIP Device"]
}

Recipe 3: Verify Tag Existence

When to use: Check whether tags have been created in the system.

{
  "TagNames": ["New Tag Name"]
}

Decision logic: If the tag name appears in the TagIds.not_found array, the tag does not exist.

1. Overview

1.1 Description

Look up tag IDs by tag names in batch. This is a utility tool for converting human-readable tag names to system tag IDs.

1.2 When to Use

• You need to set tags on devices but only know the tag names
• Verify whether tags exist in the system
• Batch retrieve IDs for multiple tags

1.3 Execution Mode and Response

This operation is synchronous and returns results immediately.

Return data includes:

• TagIds.found: Mapping of found tag names to IDs
• TagIds.not_found: List of tag names that were not found

1.4 Prerequisites

1.5 Prerequisite Tools

No prerequisites.

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`TagNames`

Array of tag names to look up.

• Type: string-array
• Format: JSON array containing one or more tag name strings
• Matching rule: Exact match, case-sensitive
• Notes:
  • Tag names must exactly match those in the system
  • Case-sensitive: Sales Department and sales department are different
  • Tags not found will appear in the not_found array
• Example:

  ["Sales Department", "Marketing", "IT Support"]

3. Outputs

3.1 Response Example

Success response (all found):

{
  "TagIds": {
    "found": {
      "Sales Department": 108,
      "Marketing": 109,
      "IT Support": 110
    },
    "not_found": []
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Success response (partially found):

{
  "TagIds": {
    "found": {
      "Sales Department": 108
    },
    "not_found": ["New York Office", "VIP Device"]
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Success response (none found):

{
  "TagIds": {
    "found": {},
    "not_found": ["NonExistent Tag 1", "NonExistent Tag 2"]
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

Error response:

{
  "TagIds": {},
  "StatusCode": -1,
  "ErrorMessage": "tag_names is required. Provide an array of tag names, e.g. [\"Department 1\", \"Department 2\"]."
}

3.2 Field Descriptions

3.3 Special Return Value Notes

• Even if some or all tags are not found, StatusCode remains 200 and ErrorMessage is empty
• Agents should check the TagIds.not_found array to determine which tags do not exist
• Tag IDs are integer type (number)

4. Examples

4.1 Basic Example: Look Up Multiple Tag IDs

Request Parameters:

{
  "TagNames": ["Sales Department", "Marketing"]
}

Response:

{
  "TagIds": {
    "found": {
      "Sales Department": 108,
      "Marketing": 109
    },
    "not_found": []
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.2 Advanced Example: Some Tags Exist

Request Parameters:

{
  "TagNames": ["Sales Department", "NonExistent Tag"]
}

Response:

{
  "TagIds": {
    "found": {
      "Sales Department": 108
    },
    "not_found": ["NonExistent Tag"]
  },
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.3 Error Example: Empty Array

Request Parameters:

{
  "TagNames": []
}

Response:

{
  "TagIds": {},
  "StatusCode": -1,
  "ErrorMessage": "tag_names is required. Provide an array of tag names, e.g. [\"Department 1\", \"Department 2\"]."
}

5. Error Handling

5.1 AB Three-Layer Error Codes

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Optimization

• Batch lookup: If you need multiple tag IDs, put them all in one TagNames array for a single query
• Cache results: Tag IDs don't change frequently; caching can reduce repeated calls

6.2 Security Considerations

🟢 Read operation: No special security requirements.

7. Related Tools

7.1 Prerequisite Tools

No prerequisites.

7.2 Follow-up Tools

7.3 Similar Tool Comparison

8. Tool Chains

8.1 Set Tags by Tag Names

Scenario: You know the tag names and need to set these tags on a device.

Tool Chain:

Get Tag IDs by Tag Names → Set Tags

Steps:

1. Call Get Tag IDs by Tag Names to get tag IDs
2. Extract tag ID array from TagIds.found
3. Call Set Tags to assign tags to the device

Example:

Input: TagNames = ["Sales", "VIP"]
Output: found = {"Sales": 101, "VIP": 102}
Use: TagIds = [101, 102] to call Set Tags

8.2 Verify and Set Tags

Scenario: Verify tags exist before setting them.

Tool Chain:

Get Tag IDs by Tag Names → [Check not_found] → Set Tags

Steps:

1. Call Get Tag IDs by Tag Names to look up tags
2. Check if TagIds.not_found is empty
3. If there are missing tags, prompt the user or skip
4. Use the found tag IDs to call Set Tags

Appendix Reference:

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