Skip to main content
POST
/
groups
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"
     }'
{
  "id": "11446498",
  "type": "group",
  "name": "Support",
  "group_type": "managed_group",
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "provenance": "Active Directory",
  "external_sync_identifier": "AD:123456",
  "description": "Support Group - as imported from Active Directory",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "permissions": {
    "can_invite_as_collaborator": true
  }
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

​
fields
string[]

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.

Body

application/json
​
name
string
required

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

Example:

"Customer Support"

​
provenance
string

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.

Maximum string length: 255
Example:

"Active Directory"

​
external_sync_identifier
string

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.

Example:

"AD:123456"

​
description
string

A human readable description of the group.

Maximum string length: 255
Example:

"\"Customer Support Group - as imported from Active Directory\""

​
invitability_level
enum<string>

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.

Available options:
admins_only,
admins_and_members,
all_managed_users
Example:

"admins_only"

​
member_viewability_level
enum<string>

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.
Available options:
admins_only,
admins_and_members,
all_managed_users
Example:

"admins_only"

Response

Returns the new group object.

Groups contain a set of users, and can be used in place of users in some operations, such as collaborations.

​
id
string
required

The unique identifier for this object.

Example:

"11446498"

​
type
enum<string>
required

The value will always be group.

Available options:
group
Example:

"group"

​
name
string

The name of the group.

Example:

"Support"

​
group_type
enum<string>

The type of the group.

Available options:
managed_group,
all_users_group
Example:

"managed_group"

​
created_at
string<date-time>

When the group object was created.

Example:

"2012-12-12T10:53:43-08:00"

​
modified_at
string<date-time>

When the group object was last modified.

Example:

"2012-12-12T10:53:43-08:00"

​
provenance
string

Keeps track of which external source this group is coming from (e.g. "Active Directory", "Google Groups", "Facebook Groups"). Setting this will also prevent Box users from editing the group name and its members directly via the Box web application. This is desirable for one-way syncing of groups.

Maximum string length: 255
Example:

"Active Directory"

​
external_sync_identifier
string

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.

Example:

"AD:123456"

​
description
string

Human readable description of the group.

Maximum string length: 255
Example:

"Support Group - as imported from Active Directory"

​
invitability_level
enum<string>

Specifies who can invite the group to collaborate on items.

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.

Available options:
admins_only,
admins_and_members,
all_managed_users
Example:

"admins_only"

​
member_viewability_level
enum<string>

Specifies who can view the members of the group (Get Memberships for 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.
Available options:
admins_only,
admins_and_members,
all_managed_users
Example:

"admins_only"

​
permissions
object

Describes the permissions that the current user has for this group.