Create a group

Tool Name: airdroid_business_create_group

Risk Level: 🟠 Medium Risk

Execution Mode: ⚡ Synchronous

Category: Group Management

Quick Start (Copy & Use)

One-liner: Create a new device group; supports creating top-level groups or sub-groups.

You need: GroupName (group name, required), ParentGroupId (parent group ID, optional, defaults to 0 for top-level group)

Success criteria: StatusCode == 200 AND ErrorMessage == "" AND GroupId > 0

What to do next: Use the returned GroupId to call Get a Group for the deploy code, or use Move Devices to a Group to assign devices to the group

Minimum request example:

{
  "GroupName": "Sales Team"
}

Minimum response example:

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

Recipes (Common Recipes)

Recipe 1: Create a top-level group

Scenario: Create a standalone top-level group

{
  "GroupName": "Marketing Department",
  "ParentGroupId": 0
}

Recipe 2: Create a sub-group

Scenario: Create a sub-group under an existing group

Step 1: Get the parent group ID

{
  "GroupName": "Sales Department"
}

Step 2: Create the sub-group

{
  "GroupName": "North Region Sales",
  "ParentGroupId": 100
}

Recipe 3: Create a group then get the deploy code

Scenario: After creating a group, retrieve its deploy code for device enrollment

Step 1: Create the group

{
  "GroupName": "New Store Devices"
}

Response:

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

Step 2: Get group details (including the deploy code)

{
  "GroupId": 12345
}

1. Overview

1.1 Description

Create a new device group in AirDroid Business. Supports creating top-level groups or sub-groups under existing groups for organizing and managing devices.

1.2 When to Use

• Organization expansion: Create device groups for new departments or regions
• Project isolation: Create separate groups for different projects for easier device management
• Hierarchical management: Build layered group structures such as "Region → Store → Device Type"
• Bulk enrollment: Create a group to obtain a deploy code for batch device registration

1.3 Execution Mode & Response

This is a synchronous operation that returns the new group's GroupId immediately.

• Return value: GroupId (unique identifier of the newly created group)
• Typical latency: < 1 second

1.4 Prerequisites

1.5 Prerequisite Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`GroupName`

Name of the new group, used to identify the group in the system.

• Type: string
• Format requirements:
  • Maximum length: 35 characters
  • Cannot be empty or contain only spaces
  • Prohibited special characters: / \ : * < > | ? ' " = ; , &
• Source: User-specified or obtained from a business system
• How to fill in a GI node:
  • Constant value: Enter a string directly, e.g. "Sales Team"
  • Upstream output reference: Get the group name from an upstream node
• Example:

"Sales Team"

Important: It is recommended to check whether a group with the same name already exists using Get a Group ID by Group Name before creating.

`ParentGroupId`

ID of the parent group, used to create nested group structures.

• Type: number (integer)
• Format requirements:
  • 0 = create a top-level group (default)
  • Positive integer > 0 = create a sub-group under the specified parent group
• Source:

How to obtain:

1. Use Get a Group ID by Group Name to look up by parent group name
2. Use the id field from the Get a Group response
3. Use the GroupId returned by Create a Group

• How to fill in a GI node:
  • Constant value: Enter a number directly, e.g. 0 or 100
  • Upstream output reference: Get from Get a Group ID by Group Name output GroupIds[0]
• Example:

0

or

100

2.3 Parameter Combination Logic

• ParentGroupId = 0 (or omitted): Creates a top-level group
• ParentGroupId > 0: Creates a sub-group under the specified parent group; the parent group must exist

3. Outputs

3.1 Response Examples

Success response:

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

Error response (group name already exists):

{
  "GroupId": 0,
  "StatusCode": 200,
  "ErrorMessage": "Group name already exists"
}

Error response (parameter error):

{
  "GroupId": 0,
  "StatusCode": -1,
  "ErrorMessage": "Invalid group_name."
}

3.2 Field Descriptions

Subsequent usage: The returned GroupId can be used with:

• Get a Group: Retrieve group details and deploy code
• Move Devices to a Group: Move devices into this group
• Update a Group Name: Modify the group name
• Update a Group Remark: Add a group remark

4. Examples

4.1 Basic Example: Create a top-level group

Request parameters:

{
  "GroupName": "Sales Team",
  "ParentGroupId": 0
}

Response:

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

4.2 Advanced Example: Create a nested sub-group

Request parameters:

{
  "GroupName": "North Region",
  "ParentGroupId": 100
}

Response:

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

4.3 Error Example: Group name already exists

Request parameters:

{
  "GroupName": "Sales Team",
  "ParentGroupId": 0
}

Response:

{
  "GroupId": 0,
  "StatusCode": 200,
  "ErrorMessage": "Group name already exists"
}

4.4 Error Example: Contains illegal characters

Request parameters:

{
  "GroupName": "Sales/Marketing",
  "ParentGroupId": 0
}

Response:

{
  "GroupId": 0,
  "StatusCode": -1,
  "ErrorMessage": "Invalid group_name."
}

5. Error Handling

5.1 AB Three-Layer Error Codes

Core principle: AB uses a three-layer error code strategy. The Agent should decide its handling approach based on the StatusCode.

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Optimization

• Batch creation: For creating multiple groups, call the tool multiple times in parallel
• Pre-check: Check whether the group name already exists before creating to avoid invalid calls

6.2 Security Considerations

🟡 Write operation: This operation creates a new resource in the system.

• Naming conventions: Establish group naming conventions for easier management
• Hierarchy control: Avoid creating excessively deep group hierarchies; recommend no more than 3 levels
• Permission management: Ensure only authorized personnel can create groups

6.3 Idempotency

Idempotency of this operation: Not idempotent.

• Calling with the same parameters multiple times will fail (group name already exists)
• It is recommended to check whether the group exists using Get a Group ID by Group Name before creating
• If you need "ensure the group exists" logic, query first and then decide whether to create

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tools Comparison

8. Tool Chains

8.1 Safe Group Creation (Avoid Duplicates)

Scenario: Ensure the group exists; create it only if it does not

Tool chain:

Get a Group ID by Group Name → [Conditional] → Create a Group

Steps:

1. Call Get a Group ID by Group Name to check if the group exists
2. If GroupIds is empty, call Create a Group to create it
3. If GroupIds is not empty, use the existing GroupId directly

8.2 Create Nested Group Structure

Scenario: Create a multi-level group structure (e.g., Region → Store)

Tool chain:

Get a Group ID by Group Name → Create a Group → Create a Group (sub-group)

Steps:

1. Check if the parent group exists
2. If it does not exist, create the parent group first
3. Use the parent group's GroupId as ParentGroupId to create the sub-group

8.3 Create a Group and Configure It

Scenario: Add a remark after creating a group

Tool chain:

Create a Group → Update a Group Remark

Steps:

1. Call Create a Group to create the new group
2. Use the returned GroupId to call Update a Group Remark to add a remark

8.4 Create a Group and Get the Deploy Code

Scenario: Retrieve the deploy code for batch device enrollment after creating a group

Tool chain:

Create a Group → Get a Group

Steps:

1. Call Create a Group to create the new group
2. Use the returned GroupId to call Get a Group
3. Retrieve deploy_code from the response for device enrollment