PUT
/groups/{group_id}Update group
Updates a specific group. Only admins of this group or users with admin-level permissions will be able to use this API.
- RetriesRetries up to 2×, 500ms backoff, 30s timeout.
group_idstringrequired
The ID of the group.
fieldsarray<string>optional
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.
namestringoptional
The name of the new group to be created. Must be unique within the
enterprise.
provenancestringoptional
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.
external_sync_identifierstringoptional
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.
descriptionstringoptional
A human readable description of the group.
invitability_levelstringoptional
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.
member_viewability_levelstringoptional
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.
200Returns the updated group object.
idstringrequired
The unique identifier for this object.
typestringrequired
The value will always be `group`.
namestringoptional
The name of the group.
group_typestringoptional
The type of the group.
created_atstringoptional
When the group object was created.
modified_atstringoptional
When the group object was last modified.
provenancestringoptional
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.
external_sync_identifierstringoptional
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.
descriptionstringoptional
Human readable description of the group.
invitability_levelstringoptional
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.
member_viewability_levelstringoptional
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.
permissionsobjectoptional
409Returns 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.
typestringoptional
The value will always be `error`.
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context
about the error. The possible fields are defined on
a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used
when contacting Box support.
defaultAn unexpected client error.
typestringoptional
The value will always be `error`.
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context
about the error. The possible fields are defined on
a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used
when contacting Box support.
Error handling
A 409 is returned: 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. Any other status is an error: An unexpected client error.