POST
/collaborationsCreate collaboration
Adds a collaboration for a single user or a single group to a file or folder.
Collaborations can be created using email address, user IDs, or a group IDs.
If a collaboration is being created with a group, access to this endpoint is dependent on the group's ability to be invited.
If collaboration is in pending status, field name is redacted when:
- a collaboration was created using
user_id, - a collaboration was created using
login.
- IdempotentThe SDK sends
Idempotency-Key, so a retried request is only applied once.
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.
notifybooleanoptional
Determines if users should receive email notification
for the action performed.
itemobjectrequired
The item to attach the comment to.
accessible_byobjectrequired
The user or group to give access to the item.
rolestringrequired
The level of access granted.
is_access_onlybooleanoptional
If set to `true`, collaborators have access to
shared items, but such items won't be visible in the
All Files list. Additionally, collaborators won't
see the path to the root folder for the
shared item.
can_view_pathbooleanoptional
Determines if the invited users can see the entire parent path to
the associated folder. The user will not gain privileges in any
parent folder and therefore can not see content the user is not
collaborated on.
Be aware that this meaningfully increases the time required to load the
invitee's **All Files** page. We recommend you limit the number of
collaborations with `can_view_path` enabled to 1,000 per user.
Only an owner or co-owners can invite collaborators with a `can_view_path` of
`true`. Only an owner can update `can_view_path` on existing collaborations.
`can_view_path` can only be used for folder collaborations.
When you delete a folder with `can_view_path=true`, collaborators may still see the parent path.
For instructions on how to remove this, see
[Even though a folder invited via can_view_path is deleted, the path remains displayed](https://support.box.com/hc/en-us/articles/37472814319891-Even-though-a-folder-invited-via-can-view-path-is-deleted-the-path-remains-displayed).
expires_atstringoptional
Set the expiration date for the collaboration. At this date, the
collaboration will be automatically removed from the item.
This feature will only work if the **Automatically remove invited
collaborators: Allow folder owners to extend the expiry date**
setting has been enabled in the **Enterprise Settings**
of the **Admin Console**. When the setting is not enabled,
collaborations can not have an expiry date and a value for this
field will be result in an error.
201Returns a new collaboration object.
idstringrequired
The unique identifier for this collaboration.
typestringrequired
The value will always be `collaboration`.
itemobjectoptional
app_itemobjectoptional
accessible_byobjectoptional
The user or group that is granted access.
invite_emailstringoptional
The email address used to invite an unregistered collaborator, if
they are not a registered user.
rolestringoptional
The level of access granted.
expires_atstringoptional
When the collaboration will expire, or `null` if no expiration
date is set.
is_access_onlybooleanoptional
If set to `true`, collaborators have access to
shared items, but such items won't be visible in the
All Files list. Additionally, collaborators won't
see the path to the root folder for the
shared item.
statusstringoptional
The status of the collaboration invitation. If the status
is `pending`, `name` returns an empty string.
acknowledged_atstringoptional
When the `status` of the collaboration object changed to
`accepted` or `rejected`.
created_byobjectoptional
created_atstringoptional
When the collaboration object was created.
modified_atstringoptional
When the collaboration object was last modified.
acceptance_requirements_statusobjectoptional
403Returns an error when the user does not have the
right permissions to create the collaboration.
* `forbidden_by_policy`: Creating a
collaboration is forbidden due to information
barrier restrictions.
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 403 is returned: Returns an error when the user does not have the right permissions to create the collaboration.
forbidden_by_policy: Creating a collaboration is forbidden due to information barrier restrictions. Any other status is an error: An unexpected client error.