Box Developer Documentation
 
    Latest version

    Create collaboration

    post
    https://api.box.com/2.0
    /collaborations

    This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.

    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, the following fields are redacted:

    • login and name are hidden if a collaboration was created using user_id,
    • name is hidden if a collaboration was created using login.

    Request

    bearer [ACCESS_TOKEN]
    application/json

    Query Parameters

    string arrayin queryoptional
    id,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.

    booleanin queryoptional
    true

    Determines if users should receive email notification for the action performed.

    Request Body

    objectin body

    The user or group to give access to the item.

    stringin bodyrequired
    "23522323"

    The ID of the user or group.

    Alternatively, use login to specify a user by email address.

    stringin bodyrequired
    "user"

    The type of collaborator to invite.

    Value is one of user,group

    stringin bodyrequired
    "john@example.com"

    The email address of the user to grant access to the item.

    Alternatively, use id to specify a user by user ID.

    booleanin bodyoptional
    true

    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 owner or co-owners can invite collaborators with a can_view_path of true.

    can_view_path can only be used for folder collaborations.

    string (date-time)in bodyoptional
    "2019-08-29T23:59:00-07:00"

    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.

    booleanin bodyoptional
    true

    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 the path to the root folder for the shared item.

    objectin body

    The item to attach the comment to.

    stringin bodyrequired
    "11446498"

    The ID of the item that will be granted access to

    stringin bodyrequired
    "file"

    The type of the item that this collaboration will be granted access to

    Value is one of file,folder

    stringin bodyrequired
    "editor"

    The level of access granted.

    Value is one of editor,viewer,previewer,uploader,previewer uploader,viewer uploader,co-owner

    Response

    application/jsonCollaboration

    Returns a new collaboration object.

    application/jsonClient error

    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.
    application/jsonClient error

    An unexpected client error.

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

    Request Example

    cURL
    curl -i -X POST "https://api.box.com/2.0/collaborations" \
         -H "authorization: Bearer <ACCESS_TOKEN>" \
         -H "content-type: application/json" \
         -d '{
           "item": {
             "type": "file",
             "id": "11446498"
           },
           "accessible_by": {
             "type": "user",
             "login": "user@example.com"
           },
           "role": "editor"
         }'

    Response Example

    {
      "id": "12345678",
      "type": "collaboration",
      "acceptance_requirements_status": {
        "strong_password_requirement": {
          "enterprise_has_strong_password_required_for_external_users": true,
          "user_has_strong_password": true
        },
        "terms_of_service_requirement": {
          "is_accepted": true,
          "terms_of_service": {
            "id": "11446498",
            "type": "terms_of_service"
          }
        },
        "two_factor_authentication_requirement": {
          "enterprise_has_two_factor_auth_enabled": true,
          "user_has_two_factor_authentication_enabled": true
        }
      },
      "accessible_by": {
        "id": "11446498",
        "type": "user",
        "is_active": true,
        "login": "ceo@example.com",
        "name": "Aaron Levie"
      },
      "acknowledged_at": "2012-12-12T10:55:20-08:00",
      "app_item": {
        "id": "12345678",
        "type": "app_item",
        "application_type": "hubs"
      },
      "created_at": "2012-12-12T10:53:43-08:00",
      "created_by": [
        {
          "id": 33224412
        },
        {
          "type": "user"
        },
        {
          "login": "dylan@example.com"
        },
        {
          "name": "Dylan Smith"
        }
      ],
      "expires_at": "2012-12-26T10:53:43-08:00",
      "invite_email": "john@example.com",
      "is_access_only": true,
      "item": {
        "id": "12345",
        "type": "file",
        "content_created_at": "2012-12-12T10:53:43-08:00",
        "content_modified_at": "2012-12-12T10:53:43-08:00",
        "created_at": "2012-12-12T10:53:43-08:00",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "login": "ceo@example.com",
          "name": "Aaron Levie"
        },
        "description": "Contract for Q1 renewal",
        "etag": "1",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "item_status": "active",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "login": "ceo@example.com",
          "name": "Aaron Levie"
        },
        "name": "Contract.pdf",
        "owned_by": {
          "id": "11446498",
          "type": "user",
          "login": "ceo@example.com",
          "name": "Aaron Levie"
        },
        "parent": {
          "id": "12345",
          "type": "folder",
          "etag": "1",
          "name": "Contracts",
          "sequence_id": "3"
        },
        "path_collection": {
          "entries": [
            {
              "etag": "1",
              "id": "12345",
              "type": "folder",
              "name": "Contracts",
              "sequence_id": "3"
            }
          ],
          "total_count": 1
        },
        "purged_at": "2012-12-12T10:53:43-08:00",
        "sequence_id": "3",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "shared_link": {
          "access": "open",
          "download_count": 3,
          "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
          "effective_access": "company",
          "effective_permission": "can_download",
          "is_password_enabled": true,
          "permissions": {
            "can_download": true,
            "can_edit": false,
            "can_preview": true
          },
          "preview_count": 3,
          "unshared_at": "2018-04-13T13:53:23-07:00",
          "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
          "vanity_name": "my_url",
          "vanity_url": "https://acme.app.box.com/v/my_url/"
        },
        "size": 629644,
        "trashed_at": "2012-12-12T10:53:43-08:00"
      },
      "modified_at": "2012-12-12T10:53:43-08:00",
      "role": "editor",
      "status": "accepted"
    }