Skip to content

Group API

The Group API manages user groups and their configurations in Unique AI.

Overview

Organize users into groups for permission management and access control.

Methods

unique_sdk.Group.create_group - Create a new group

Compatibility

Compatible with release >.48

Create a new group in a company.

Parameters:

  • name (str, required) - Group name
  • externalId (str, optional) - External system ID
  • parentId (str, optional) - Parent group ID for nesting

Returns:

Returns a Group object.

Example:

1
2
3
4
5
6
7
8
9
group = unique_sdk.Group.create_group(
    user_id=user_id,
    company_id=company_id,
    name="Engineering Team",
    externalId="ext_eng_001",
    parentId="group_parent123"
)

print(f"Created group: {group.id}")
unique_sdk.Group.get_groups - Get groups with filtering

Compatibility

Compatible with release >.48

Get groups with optional filtering and pagination.

Parameters:

  • skip (int, optional) - Number of records to skip (default: 0)
  • take (int, optional) - Number of records to return (default: 50, max: 1000)
  • name (str, optional) - Filter by group name

Returns:

Returns a Groups object.

Example:

1
2
3
4
5
6
groups = unique_sdk.Group.get_groups(
    user_id=user_id,
    company_id=company_id,
    skip=0,
    take=50
)

Filter by Name:

1
2
3
4
5
groups = unique_sdk.Group.get_groups(
    user_id=user_id,
    company_id=company_id,
    name="Admin"
)
unique_sdk.Group.update_group - Update group name

Compatibility

Compatible with release >.48

Update a group's name.

Parameters:

  • group_id (str, required) - Group ID to update
  • name (str, optional) - New group name

Returns:

Returns a Group object.

Example:

1
2
3
4
5
6
updated_group = unique_sdk.Group.update_group(
    user_id=user_id,
    company_id=company_id,
    group_id="group_a9cs7wr2z1bg2sxczvltgjch",
    name="New Group Name"
)
unique_sdk.Group.add_users_to_group - Add users to group

Compatibility

Compatible with release >.48

Add multiple users to a group.

Parameters:

  • group_id (str, required) - Group ID to add users to
  • userIds (List[str], required) - List of user IDs to add

Returns:

Returns an AddUsersToGroupResponse object.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
result = unique_sdk.Group.add_users_to_group(
    user_id=user_id,
    company_id=company_id,
    group_id="group_a9cs7wr2z1bg2sxczvltgjch",
    userIds=[
        "299420877169688584",
        "325402458132058201",
        "299426678160031752"
    ]
)
unique_sdk.Group.remove_users_from_group - Remove users from group

Compatibility

Compatible with release >.48

Remove multiple users from a group.

Parameters:

  • group_id (str, required) - Group ID to remove users from
  • userIds (List[str], required) - List of user IDs to remove

Returns:

Returns a RemoveUsersFromGroupResponse object.

Example:

1
2
3
4
5
6
7
8
9
result = unique_sdk.Group.remove_users_from_group(
    user_id=user_id,
    company_id=company_id,
    group_id="group_a9cs7wr2z1bg2sxczvltgjch",
    userIds=[
        "299426678160031752",
        "299426678160031752"
    ]
)
unique_sdk.Group.update_group_configuration - Update group configuration

Compatibility

Compatible with release >.48

Update group configuration (JSON object).

Parameters:

  • group_id (str, required) - Group ID to update
  • configuration (Dict[str, Any], required) - Group configuration dictionary

Returns:

Returns a GroupWithConfiguration object.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
updated_group = unique_sdk.Group.update_group_configuration(
    user_id=user_id,
    company_id=company_id,
    group_id="group_abc123",
    configuration={
        "email": "team@unique.ai",
        "department": "Engineering",
        "budget_code": "ENG-2024"
    }
)
unique_sdk.Group.delete_group - Delete a group

Compatibility

Compatible with release >.48

Delete a group by ID.

Parameters:

  • group_id (str, required) - Group ID to delete

Returns:

Returns a DeleteResponse object.

Example:

1
2
3
4
5
result = unique_sdk.Group.delete_group(
    user_id=user_id,
    company_id=company_id,
    group_id="group_a9cs7wr2z1bg2sxczvltgjch"
)

Use Cases

Team Setup 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
def setup_department_teams(company_id, admin_user_id):
    """Create department structure with teams."""

    # Create parent group
    engineering = unique_sdk.Group.create_group(
        user_id=admin_user_id,
        company_id=company_id,
        name="Engineering"
    )

    # Create sub-teams
    teams = ["Backend", "Frontend", "DevOps"]
    for team_name in teams:
        team = unique_sdk.Group.create_group(
            user_id=admin_user_id,
            company_id=company_id,
            name=team_name,
            parentId=engineering.id
        )
        print(f"Created: Engineering > {team_name}")

    return engineering.id

setup_department_teams(company_id, admin_user_id)
Bulk User Management 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
def assign_users_to_teams(user_email_list, team_id, company_id, admin_user_id):
    """Assign multiple users to a team."""

    # Find users by email
    user_ids = []
    for email in user_email_list:
        result = unique_sdk.User.get_users(
            user_id=admin_user_id,
            company_id=company_id,
            email=email
        )
        if result.data:
            user_ids.append(result.data[0].id)

    # Add to group
    if user_ids:
        unique_sdk.Group.add_users_to_group(
            user_id=admin_user_id,
            company_id=company_id,
            group_id=team_id,
            userIds=user_ids
        )
        print(f"Added {len(user_ids)} users to team")

# Usage
assign_users_to_teams(
    ["john@example.com", "jane@example.com"],
    "group_backend_team",
    company_id,
    admin_user_id
)
Permission Management 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
def grant_folder_access_to_group(group_id, folder_paths, access_type="READ"):
    """Grant group access to multiple folders."""

    for path in folder_paths:
        unique_sdk.Folder.add_access(
            user_id=admin_user_id,
            company_id=company_id,
            folderPath=path,
            scopeAccesses=[{
                "entityId": group_id,
                "type": access_type,  # "READ" or "WRITE"
                "entityType": "GROUP"
            }],
            applyToSubScopes=True
        )
        print(f"Granted {access_type} access: {path}")

# Grant engineering team access to their docs
engineering_group_id = "group_engineering"
grant_folder_access_to_group(
    engineering_group_id,
    ["/Company/Engineering", "/Company/Technical_Docs"],
    "WRITE"
)
Group Configuration 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
def configure_team(group_id, team_config):
    """Configure team settings."""

    return unique_sdk.Group.update_group_configuration(
        user_id=admin_user_id,
        company_id=company_id,
        group_id=group_id,
        configuration=team_config
    )

# Configure team
configure_team(
    "group_backend_team",
    {
        "slack_channel": "#backend-team",
        "oncall_rotation": ["user1", "user2", "user3"],
        "manager": "299420877169688584"
    }
)

Best Practices

Hierarchical Organization 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Create department -> team -> sub-team hierarchy
dept = unique_sdk.Group.create_group(name="Engineering")

team = unique_sdk.Group.create_group(
    name="Backend",
    parentId=dept.id
)

subteam = unique_sdk.Group.create_group(
    name="API Team",
    parentId=team.id
)

Return Types

Group

The Group object represents a group in the company

Fields:

  • id (str) - Unique group identifier
  • name (str) - Group name
  • externalId (str) - External system identifier
  • parentId (str | None) - Parent group ID for nesting
  • members (List[GroupMember] | None) - List of group members. See Group.GroupMember for structure.
  • createdAt (str) - Creation timestamp (ISO 8601)
  • updatedAt (str) - Last update timestamp (ISO 8601)

Returned by: Group.create_group(), Group.update_group()

GroupMember

The GroupMember object represents a member of a group

Fields:

  • entityId (str) - User ID of the member

Used in: Group.members

GroupWithConfiguration

The GroupWithConfiguration object represents a group with configuration

Fields:

  • All fields from Group
  • configuration (Dict[str, Any]) - Group configuration dictionary

Returned by: Group.update_group_configuration()

Groups

The Groups object contains a list of groups

Fields:

  • groups (List[Group]) - List of group objects. See Group for structure.

Returned by: Group.get_groups()

AddUsersToGroupResponse

The AddUsersToGroupResponse object contains membership information

Fields:

  • memberships (List[GroupMembership]) - List of created memberships. See GroupMembership for structure.

Returned by: Group.add_users_to_group()

GroupMembership

The GroupMembership object represents a membership relationship

Fields:

  • entityId (str) - User ID
  • groupId (str) - Group ID
  • createdAt (str) - Creation timestamp (ISO 8601)

Used in: AddUsersToGroupResponse.memberships

RemoveUsersFromGroupResponse

The RemoveUsersFromGroupResponse object indicates removal success

Fields:

  • success (bool) - Whether removal was successful

Returned by: Group.remove_users_from_group()

DeleteResponse

The DeleteResponse object contains the deleted group ID

Fields:

  • id (str) - ID of the deleted group

Returned by: Group.delete_group()