Join BoxWorks 2024 to discover what's possible with content and AI!

Create group

post

https://api.box.com/2.0

/groups

Creates a new group of users in an enterprise. Only users with admin permissions can create new groups.

Request

authorizationbearer [ACCESS_TOKEN]

content-typeapplication/json

Query Parameters

fields string arrayin queryoptional

exampleid,type,name

A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response.

Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.

Request Body

description stringin bodyoptional

example""Customer Support Group - as imported from Active Directory""max length255

A human readable description of the group.

external_sync_identifier stringin bodyoptional

example"AD:123456"

An arbitrary identifier that can be used by external group sync tools to link this Box Group to an external group.

Example values of this field could be an Active Directory Object ID or a Google Group ID.

We recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems.

invitability_level stringin bodyoptional

example"admins_only"

Specifies who can invite the group to collaborate on folders.

When set to admins_only the enterprise admin, co-admins, and the group's admin can invite the group.

When set to admins_and_members all the admins listed above and group members can invite the group.

When set to all_managed_users all managed users in the enterprise can invite the group.

Value is one of admins_only,admins_and_members,all_managed_users

member_viewability_level stringin bodyoptional

example"admins_only"

Specifies who can see the members of the group.

admins_only - the enterprise admin, co-admins, group's group admin
admins_and_members - all admins and group members
all_managed_users - all managed users in the enterprise

Value is one of admins_only,admins_and_members,all_managed_users

name stringin bodyrequired

example"Customer Support"

The name of the new group to be created. This name must be unique within the enterprise.

provenance stringin bodyoptional

example"Active Directory"max length255

Keeps track of which external source this group is coming, for example Active Directory, or Okta.

Setting this will also prevent Box admins from editing the group name and its members directly via the Box web application.

This is desirable for one-way syncing of groups.

Response

201application/jsonGroup (Full)

Returns the new group object.

409application/jsonClient error

Returns an error a conflict is stopping the group from being created.

invalid_parameter: Often returned if the group name is not unique in the enterprise.

defaultapplication/jsonClient error

An unexpected client error.

post

Create group

You can now try out some of our APIs live, right here in the documentation.

Request Example

cURL

curl -i -X POST "https://api.box.com/2.0/groups" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "name": "Customer Support"
     }'

TypeScript Gen

await client.groups.createGroup({
  name: groupName,
  description: groupDescription,
} satisfies CreateGroupRequestBody);

Python Gen

client.groups.create_group(group_name, description=group_description)

.NET Gen

await client.Groups.CreateGroupAsync(requestBody: new CreateGroupRequestBody(name: groupName) { Description = groupDescription });

Swift Gen (Beta)

try await client.groups.createGroup(requestBody: CreateGroupRequestBody(name: groupName, description: groupDescription))

Java

BoxGroup.Info groupInfo = BoxGroup.createGroup(api, "My Group");

Python

created_group = client.create_group('Example Group')
print(f'Created group with ID {created_group.id}')

.NET

var groupParams = new BoxGroupRequest()
{
    Name = "Engineers"
};
BoxGroup group = await client.GroupsManager.CreateAsync(groupParams);

Node

client.groups.create('My group', {description: 'An example group'})
	.then(group => {
		/* group -> {
			type: 'group',
			id: '119720',
			name: 'Box Employees',
			created_at: '2013-05-16T15:27:57-07:00',
			modified_at: '2013-05-16T15:27:57-07:00' }
		*/
	});

iOS

client.groups.create(name: "Team A", provenance: "Test", externalSyncIdentifier: "Test Sync", description: "Test Description", invitabilityLevel: .allManagedUsers, memberViewabilityLevel: .allManagedUsers) { (result: Result<Group, BoxSDKError>) in
    guard case let .success(group) = result else {
        print("Error creating new group")
        return
    }

    print("Group \(group.name) was created")
 }

Response Example

{
  "id": "11446498",
  "type": "group",
  "created_at": "2012-12-12T10:53:43-08:00",
  "description": "Support Group - as imported from Active Directory",
  "external_sync_identifier": "AD:123456",
  "group_type": "managed_group",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "name": "Support",
  "permissions": {
    "can_invite_as_collaborator": true
  },
  "provenance": "Active Directory"
}