# Box Box is a cloud content management platform for secure file storage, sharing, collaboration, and governance. - **Category:** file management & storage - **Auth:** OAUTH2 - **Composio Managed App Available?** Yes - **Tools:** 286 - **Triggers:** 20 - **Slug:** `BOX` - **Version:** 20260323_00 ## Tools ### Add domain to list of allowed collaboration domains **Slug:** `BOX_ADD_ALLOWED_COLLABORATION_DOMAIN` Creates a new entry in the list of allowed domains for collaboration within your enterprise. This allows you to whitelist specific domains for external collaboration. Use 'inbound' to allow users from the specified domain to collaborate on your enterprise's files and folders. Use 'outbound' to allow your enterprise users to collaborate on content owned by the specified domain. Use 'both' for bidirectional collaboration. Note: This action requires enterprise admin privileges and the 'manage_enterprise_properties' scope. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `domain` | string | Yes | The domain to add to the list of allowed collaboration domains (e.g., 'example.com'). This domain will be whitelisted for collaboration with your enterprise based on the specified direction. | | `direction` | string ("both" | "inbound" | "outbound") | Yes | The direction in which collaborations are allowed. Use 'inbound' to allow external users from this domain to collaborate on your content, 'outbound' to allow your users to collaborate on their content, or 'both' for bidirectional collaboration. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Add classification to file **Slug:** `BOX_ADD_CLASSIFICATION_TO_FILE` Adds a classification to a file by specifying the label of the classification to add. **Enterprise-only feature**: This action requires a Box enterprise account with classification templates configured. Users without an enterprise account will receive an error when attempting to use this feature. This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `Box__Security__Classification__Key` | string | Yes | The name of the classification to apply to this file. This is a required field. To list the available classifications in an enterprise, use the classification API to retrieve the [classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema) which lists all available classification keys. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Add classification to folder **Slug:** `BOX_ADD_CLASSIFICATION_TO_FOLDER` Adds a classification to a folder by specifying the label of the classification to add. **Enterprise-only feature**: This action requires a Box enterprise account with classification templates configured. Users without an enterprise account will receive an error when attempting to use this feature. **Prerequisites**: - A classification template must exist in the enterprise. Use `list_all_classifications` to retrieve available classification keys. - If no classifications exist, an admin must first create the classification template using `add_initial_classifications`. **Common errors**: - 404: Classification template not found (no classifications exist in enterprise) - 409: Classification already exists on this folder (use update action instead) - 403: Insufficient permissions to add classifications This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `Box__Security__Classification__Key` | string | Yes | The name of the classification to apply to this folder. This is a required field. To list the available classifications in an enterprise, use the classification API to retrieve the [classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema) which lists all available classification keys. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Add initial classifications **Slug:** `BOX_ADD_INITIAL_CLASSIFICATIONS` Initializes the classification template for an enterprise with an initial set of classification options. IMPORTANT: This action requires admin permissions and should only be called once per enterprise when no classifications exist. If classifications already exist, use the 'add_classification' action to add more options. Common classification examples: 'Confidential', 'Internal', 'Public', 'Restricted'. Returns 400 if the classification template already exists. Returns 403 if the user lacks admin permissions. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string ("enterprise") | Yes | The scope for the classification template. Must be 'enterprise'. | | `fields` | array | Yes | The classification field definition. Must contain exactly one field of type 'enum' that holds all valid classification values. | | `hidden` | boolean | No | Whether to hide the classification template from web and mobile interfaces. | | `displayName` | string ("Classification") | Yes | The display name. Must be 'Classification'. | | `templateKey` | string ("securityClassification-6VMVochwUWo") | Yes | The template key. Must be 'securityClassification-6VMVochwUWo'. | | `copyInstanceOnItemCopy` | boolean | No | Whether to copy classifications when a file or folder is copied. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Add or update user avatar **Slug:** `BOX_ADD_OR_UPDATE_USER_AVATAR` Adds or updates a user avatar. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `pic` | object | Yes | The avatar image file to upload. Requirements: file must be.jpg or.png format, maximum 1MB size, maximum 1024x1024 pixels. | | `user_id` | string | Yes | The ID of the user. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Add shared link to file **Slug:** `BOX_ADD_SHARED_LINK_TO_FILE` Adds a shared link to a file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | Explicitly request the `shared_link` fields to be returned for this item. Defaults to 'shared_link' to return the shared link details in the response. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `shared__link__access` | string ("collaborators" | "company" | "open") | No | The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the file (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. | | `shared__link__password` | string | No | The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`. | | `shared__link__unshared__at` | string | No | The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. | | `shared__link__vanity__name` | string | No | Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. | | `shared__link__permissions__can__edit` | boolean | No | If the shared link allows for editing of files. This can only be set when `access` is set to `open` or `company`. This value can only be `true` is `can_download` is also `true`. | | `shared__link__permissions__can__preview` | boolean | No | If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. | | `shared__link__permissions__can__download` | boolean | No | If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Add shared link to folder **Slug:** `BOX_ADD_SHARED_LINK_TO_FOLDER` Adds a shared link to a folder, allowing it to be shared with others via a URL. This action creates or updates a shared link on a folder. The shared link can be configured with different access levels: - 'open': Anyone with the link can access - 'company': Only people within the company can access (paid accounts only) - 'collaborators': Only those invited to the folder can access To create a shared link with default enterprise settings, call with just folder_id and fields='shared_link'. To customize access, set shared_link_access parameter. Returns the folder object with the new shared_link information including the URL. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | Comma-separated list of fields to return. To retrieve shared link details, use 'shared_link'. Example values: 'shared_link', 'shared_link,name,id'. | | `folder_id` | string | Yes | The unique identifier that represents a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: '12345678'. | | `shared__link__access` | string ("collaborators" | "company" | "open") | No | The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. | | `shared__link__password` | string | No | The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`. | | `shared__link__unshared__at` | string | No | The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. | | `shared__link__vanity__name` | string | No | Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. | | `shared__link__permissions__can__edit` | boolean | No | This value can only be `false` for items with a `type` of `folder`. | | `shared__link__permissions__can__preview` | boolean | No | If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. | | `shared__link__permissions__can__download` | boolean | No | If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Add shared link to web link **Slug:** `BOX_ADD_SHARED_LINK_TO_WEB_LINK` Adds a shared link to a web link. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | Comma-separated list of fields to include in the response. Set to 'shared_link' to return shared link details. Defaults to 'shared_link'. | | `web_link_id` | string | Yes | The unique identifier (ID) of the web link to add a shared link to. | | `shared__link__access` | string ("collaborators" | "company" | "open") | No | The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the file (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. | | `shared__link__password` | string | No | The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`. | | `shared__link__unshared__at` | string | No | The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. | | `shared__link__vanity__name` | string | No | Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. | | `shared__link__permissions__can__edit` | boolean | No | This value can only be `true` is `type` is `file`. | | `shared__link__permissions__can__preview` | boolean | No | If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. | | `shared__link__permissions__can__download` | boolean | No | If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Add user to group **Slug:** `BOX_ADD_USER_TO_GROUP` Creates a group membership. Only users with admin-level permissions will be able to use this API. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `role` | string ("admin" | "member") | No | The role of the user in the group. Can be 'admin' or 'member'. Admins have elevated permissions to manage the group. Members have standard access. Defaults to 'member' if not specified. | | `fields` | array | No | 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. | | `user__id` | string | Yes | The unique identifier (ID) of the user to add to the group. This is a required field. | | `group__id` | string | Yes | The unique identifier (ID) of the group to add the user to. This is a required field. | | `configurable_permissions` | object | No | Custom configuration for the permissions an admin of a group will receive. This option has no effect on members with a role of 'member'. Setting these permissions overwrites the default access levels of an admin. Specifying a value of null for this object will disable all configurable permissions. Specifying permissions will set them accordingly, omitted permissions will be enabled by default. Example: {'can_run_reports': true, 'can_instant_login': false}. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Append metadata taxonomy level **Slug:** `BOX_APPEND_METADATA_TAXONOMY_LEVEL` Appends a new level to a metadata taxonomy structure. Use when adding hierarchical categories to organize metadata. If no levels exist, this creates the first level. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `namespace` | string | Yes | The namespace of the metadata taxonomy. Use format 'enterprise_{enterprise_id}' for enterprise taxonomies (e.g., 'enterprise_123456'). | | `description` | string | No | The description of the taxonomy level. Provides additional context about this level (e.g., 'French Republic', 'Second level taxonomy for testing'). | | `displayName` | string | Yes | The display name of the taxonomy level to append. This is the label shown to users (e.g., 'France', 'Level 2'). | | `taxonomy_key` | string | Yes | The key of the metadata taxonomy to append the level to (e.g., 'geography', 'product_catalog'). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Apply watermark to file **Slug:** `BOX_APPLY_WATERMARK_TO_FILE` Applies or update a watermark on a file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `watermark__imprint` | string ("default") | No | The type of watermark to apply. Currently only supports 'default'. This value is required by the Box API. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Apply watermark to folder **Slug:** `BOX_APPLY_WATERMARK_TO_FOLDER` Applies or update a watermark on a folder. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `watermark__imprint` | string ("default") | No | The type of watermark to apply. Currently only supports 'default' as the value. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Ask question **Slug:** `BOX_ASK_QUESTION` Ask questions about Box files using Box AI. Use this action to query one or more files with natural language questions. Box AI will analyze the file contents and provide an answer based on the information found in the files. Modes: - single_item_qa: Ask about a single file (items array must have exactly 1 element) - multiple_item_qa: Ask about multiple files (up to 25 files) Limitations: - Text documents: Up to 1MB per file, max 25 files - Images: 1024x1024px resolution, max 5 images/pages - Prompts: Max 10,000 characters Requires 'manage_ai' scope in the access token. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mode` | string ("multiple_item_qa" | "single_item_qa") | Yes | The query mode: 'single_item_qa' for questions about one file (items array must have exactly 1 element), or 'multiple_item_qa' for questions across multiple files (up to 25 files). | | `items` | array | Yes | List of files to query. For 'single_item_qa' mode, provide exactly 1 item. For 'multiple_item_qa' mode, provide 1-25 items. Each item needs 'id' and 'type' fields. | | `prompt` | string | Yes | The question to ask about the file(s). Maximum 10,000 characters. | | `ai_agent` | object | No | Schema for specifying a custom AI agent to handle the request. | | `dialogue_history` | array | No | Optional conversation history to provide context for follow-up questions. | | `include_citations` | boolean | No | Set to true to include source citations in the response showing where the answer came from. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Assign legal hold policy **Slug:** `BOX_ASSIGN_LEGAL_HOLD_POLICY` Assign a legal hold policy to a file, file version, folder, or user. Legal hold policies preserve content for litigation or compliance purposes by preventing the deletion of specified items. When assigned to a folder, the hold applies recursively to all contents. When assigned to a user, the hold applies to all content owned by that user. Note: This feature requires Box Enterprise or higher with legal hold capabilities enabled. The authenticated user must have admin privileges with 'manage_legal_holds' scope. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `policy_id` | string | Yes | The unique identifier of the legal hold policy to assign. Obtain this ID from 'create_legal_hold_policy' or 'list_all_legal_hold_policies'. | | `assign__to__id` | string | Yes | The unique identifier of the item to assign the legal hold policy to. Must correspond to the type specified in assign_to_type. | | `assign__to__type` | string ("file" | "file_version" | "folder" | "user" | "ownership" | "interactions") | Yes | The type of item to assign the policy to. Options: 'file' (individual files), 'file_version' (specific file versions), 'folder' (applies recursively to all contents), 'user' (all content owned by a user), 'ownership' (ownership records), or 'interactions' (user interactions with content). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Assign retention policy **Slug:** `BOX_ASSIGN_RETENTION_POLICY` Assigns a retention policy to an item in Box to enforce content retention. Use this action to apply a retention policy to: - An entire enterprise (assign_to_type='enterprise', no ID needed) - A specific folder (assign_to_type='folder', provide folder ID) - Items matching metadata criteria (assign_to_type='metadata_template', provide template ID) Prerequisites: - Box Governance license is required - Admin permissions with 'manage_data_retention' and 'enterprise_content' scopes - A retention policy must exist (use create_retention_policy first) Example usage for folder assignment: - policy_id: "173463" (from create_retention_policy or list_retention_policies) - assign_to_type: "folder" - assign_to_id: "6564564" (the folder ID) #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `policy_id` | string | Yes | The unique ID of the retention policy to assign (e.g., '173463'). Get this from list_retention_policies or create_retention_policy. | | `filter_fields` | array | No | Optional metadata filters when assign_to_type is 'metadata_template'. Array of objects with 'field' (metadata attribute key ID) and 'value' (field value ID). Only enum and multiselect field types are supported. Currently limited to one filter object. | | `assign__to__id` | string | No | The ID of the target item. Required for 'folder' (folder ID like '6564564') and 'metadata_template' (template ID). Omit or set to null when assign_to_type is 'enterprise'. | | `assign__to__type` | string ("enterprise" | "folder" | "metadata_template") | Yes | The type of item to assign the policy to. Options: 'enterprise' (applies to all enterprise content), 'folder' (applies to specific folder by ID), 'metadata_template' (applies based on metadata criteria). | | `start_date_field` | string | No | The date field that determines when retention begins. For 'metadata_template' assignments, this can be a date field's metadata attribute key ID (e.g., 'upload_date'). Only applicable when assign_to_type is 'metadata_template'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Assign storage policy **Slug:** `BOX_ASSIGN_STORAGE_POLICY` Creates a storage policy assignment for an enterprise or user. Storage policies control where data is stored geographically (data residency). This action requires Box Zones or similar enterprise feature to be enabled. Use 'list_storage_policies' to get available policies before assignment. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `assigned__to__id` | string | Yes | The ID of the entity to assign the policy to. If assigned_to_type is 'user', provide a user ID. If 'enterprise', provide the enterprise ID. | | `assigned__to__type` | string ("enterprise" | "user") | Yes | The type of entity to assign the storage policy to. Use 'user' to assign to a specific user, or 'enterprise' to set the default policy for the entire enterprise. | | `storage__policy__id` | string | Yes | The unique ID of the storage policy to assign. Get available policies using the 'list_storage_policies' action. | | `storage__policy__type` | string ("storage_policy") | No | The type of policy to assign. Must be 'storage_policy'. This field is fixed and agents typically don't need to specify it. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Assign task **Slug:** `BOX_ASSIGN_TASK` Assigns a task to a user. A task can be assigned to more than one user by creating multiple assignments. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task__id` | string | Yes | The unique identifier of the task to assign. Required. | | `task__type` | string ("task") | No | The type of the item being assigned. Must be 'task'. | | `assign__to__id` | string | No | The user ID of the person to assign the task to. Either this or `assign_to_login` must be provided, but not both. | | `assign__to__login` | string | No | The email address (login) of the user to assign the task to. Either this or `assign_to_id` must be provided, but not both. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Authorize user **Slug:** `BOX_AUTHORIZE_USER` Authorize a user by sending them through the [Box](https://box.com) website and request their permission to act on their behalf. This is the first step when authenticating a user using OAuth 2.0. To request a user's authorization to use the Box APIs on their behalf you will need to send a user to the URL with this format. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string | No | A space-separated list of application scopes to request (e.g., 'root_readwrite manage_users'). Defaults to all scopes configured for the application if not specified. | | `state` | string | No | A custom string of your choice. Box will pass the same string to the redirect URL when authentication is complete. This parameter can be used to identify a user on redirect, as well as protect against hijacked sessions and other exploits. | | `client_id` | string | Yes | The Client ID of the application requesting to authenticate the user. Found in the Box developer console under your application's OAuth 2.0 Parameters section. | | `redirect_uri` | string | No | The HTTPS URI to which Box redirects the browser after the user grants or denies permission. Must match one of the redirect URIs configured in your Box application. Required if multiple redirect URIs are configured; otherwise a 'redirect_uri_missing' error occurs. | | `response_type` | string ("code") | Yes | The type of response to receive. Must be 'code' for the authorization code grant flow. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Cancel box sign request **Slug:** `BOX_CANCEL_BOX_SIGN_REQUEST` Cancels a pending Box Sign request that has not yet been fully signed or declined. After cancellation, any outstanding signers will no longer be able to sign the document. Only the user who created the request (the requester) is able to cancel it. Note: A request cannot be cancelled if it was already declined, fully signed, or if the document is still in the converting state. Returns the cancelled sign request object with updated status set to 'cancelled'. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sign_request_id` | string | Yes | The unique identifier of the Box Sign request to cancel. This ID is returned when creating a sign request or can be retrieved from the list of sign requests. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Commit upload session **Slug:** `BOX_COMMIT_UPLOAD_SESSION` Commits an upload session and creates a file from the uploaded chunks. This is the final step in a chunked upload workflow: 1. Create an upload session using 'create_upload_session' 2. Upload file parts using 'upload_part_of_file' 3. Commit the session using this action to finalize the file Requirements: - All parts must be uploaded before committing - The digest header must contain the SHA1 hash of the entire file (Base64 encoded) - Parts array must include part_id, offset, and size for each uploaded chunk Note: The API may return 202 if processing is not complete. In this case, check the retry_after field and retry after the specified number of seconds. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `parts` | array | Yes | List of uploaded parts to commit. Each part must include: 'part_id' (string), 'offset' (integer byte position), 'size' (integer bytes). Optionally includes 'sha1' (string hash of the part). These values are returned by the upload part API. | | `digest` | string | Yes | The Base64-encoded SHA1 hash of the entire file being uploaded. Format should be the raw Base64 string (e.g., 'fpRyg5eVQletdZqEKaFlqwBXJzM='). The 'sha=' prefix will be added automatically. | | `if_match` | string | No | Optional. The last known ETag value of the upload session. If provided, the request fails with 412 if the session has changed. | | `attributes` | object | No | Optional file attributes to set on the uploaded file, such as 'content_modified_at' (ISO 8601 timestamp). Example: {'content_modified_at': '2024-01-15T12:00:00Z'}. | | `if_none_match` | string | No | Optional. ETag value to check for changes. Request fails with 304 if item unchanged. | | `upload_session_id` | string | Yes | The ID of the upload session to commit. This is returned when creating an upload session. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Copy file **Slug:** `BOX_COPY_FILE` Creates a copy of a file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | An optional new name for the copied file. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (`/`, ``), and protected names like `.` and `..` are automatically sanitized by removing the non-allowed characters. | | `fields` | array | No | 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. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `version` | string | No | An optional ID of the specific file version to copy. | | `parent__id` | string | Yes | The ID of folder to copy the file to. This parameter is required - the destination folder must be specified. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Copy file request **Slug:** `BOX_COPY_FILE_REQUEST` Copies an existing file request to a new folder. File requests allow external users to upload files to a specific folder without needing a Box account. This action creates a copy of an existing file request and associates it with a different destination folder. IMPORTANT LIMITATION: File request IDs cannot be discovered via API - they can only be obtained from the Box web application. To find a file_request_id: 1. Navigate to Box web UI (https://app.box.com) 2. Go to the folder containing the file request 3. Open the file request settings 4. Copy the ID from the URL (e.g., https://*.app.box.com/filerequest/123 → ID is "123") Common use cases: - Creating file request templates that can be copied to multiple project folders - Automating file request creation for new cases/customers/projects - Duplicating file requests with different settings (title, description, etc.) When copying, you can optionally override settings from the source file request including title, description, status, and form requirements. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `title` | string | No | The title to use for the copied file request. This is displayed to uploaders on the file request form. If not provided, the title from the source file request is used. | | `folder` | object | Yes | The destination folder to associate with the copied file request. Must include the folder 'id' field. | | `status` | string ("active" | "inactive") | No | Status of the file request. | | `expires_at` | string | No | The date after which the copied file request will no longer accept submissions (ISO 8601 format, e.g., '2030-12-31T23:59:59Z'). After this date, the status is automatically set to 'inactive'. If not provided, no expiration is set. | | `description` | string | No | The description to use for the copied file request. This is displayed to uploaders on the file request form. If not provided, the description from the source file request is used. | | `file_request_id` | string | Yes | The unique identifier of the file request to copy. IMPORTANT: File request IDs can ONLY be obtained from the Box web application URL - there is no API to list file requests. Visit a file request in the Box web UI (e.g., https://*.app.box.com/filerequest/123) and copy the ID from the URL. In this example, the file_request_id would be '123'. | | `is_email_required` | boolean | No | Whether uploaders must provide their email address when submitting files to the copied file request. If not provided, the setting from the source file request is used. | | `is_description_required` | boolean | No | Whether uploaders must provide a description when submitting files to the copied file request. If not provided, the setting from the source file request is used. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Copy folder **Slug:** `BOX_COPY_FOLDER` Creates a copy of a folder within a destination folder. The original folder will not be changed. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | An optional new name for the copied folder. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (`/`, ``), as well as names with trailing spaces are prohibited. Additionally, the names `.` and `..` are not allowed either. | | `fields` | array | No | 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. | | `folder_id` | string | Yes | The unique identifier of the folder to copy. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder with the ID `0` can not be copied. | | `parent__id` | string | Yes | The ID of the destination folder where the copy will be placed. Use '0' to copy to the root folder (All Files). This is a required field. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create AI Agent **Slug:** `BOX_CREATE_AI_AGENT` Creates a custom AI agent in Box AI Studio. At least one capability required: ask (Q&A), text_gen (content generation), or extract (metadata extraction). Requirements: Box Enterprise Advanced account, Box AI Studio enabled, "Manage AI" scope in Developer Console. Access options: 'enabled' (all users), 'disabled' (none), 'enabled_for_selected_users' (specified in allowed_entities). Example: Set name + ask__type='ai_agent_ask' + ask__access__state='enabled' + ask__description to create Q&A agent. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | The display name of the AI Agent visible to users in the Box interface. | | `type` | string ("ai_agent") | No | The type of agent. Must be 'ai_agent'. | | `ask__type` | string ("ai_agent_ask") | No | Type identifier for ask capability. Must be 'ai_agent_ask' when enabling this capability. | | `access_state` | string | No | Access control for the agent. Options: 'enabled' (all enterprise users), 'disabled' (no access), 'enabled_for_selected_users' (only specified users/groups in allowed_entities). | | `extract__type` | string ("ai_agent_extract") | No | Type identifier for extract capability. Must be 'ai_agent_extract' when enabling this capability. | | `icon_reference` | string | No | Avatar icon URL for the agent. Format: https://cdn01.boxcdn.net/app-assets/aistudio/avatars/. Available icons: logo_boxAi, logo_stamp, logo_legal, logo_finance, logo_config, logo_handshake, logo_analytics, logo_classification (both .png and .svg supported). Example: https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg | | `text__gen__type` | string ("ai_agent_text_gen") | No | Type identifier for text generation capability. Must be 'ai_agent_text_gen' when enabling this capability. | | `allowed_entities` | array | No | Users/groups with access when access_state='enabled_for_selected_users'. Format: [{'type': 'user'\|'group', 'id': ''}] | | `ask__description` | string | No | User-facing description of what questions this agent can answer. | | `ask__access__state` | string | No | Enable state for ask capability. Options: 'enabled', 'disabled'. | | `extract__description` | string | No | User-facing description of what metadata/data this agent can extract from documents. | | `extract__access__state` | string | No | Enable state for extract capability. Options: 'enabled', 'disabled'. | | `text__gen__description` | string | No | User-facing description of what content this agent can generate. | | `text__gen__access__state` | string | No | Enable state for text generation capability. Options: 'enabled', 'disabled'. | | `ask__custom__instructions` | string | No | System prompt/instructions defining agent behavior, tone, and constraints for answering questions. | | `ask__suggested__questions` | array | No | Up to 4 suggested questions shown to users. Example: ['What is in this file?', 'Summarize the key points'] | | `extract__custom__instructions` | string | No | System prompt/instructions defining extraction rules, field mappings, and output formatting. | | `text__gen__custom__instructions` | string | No | System prompt/instructions defining writing style, format, and content generation guidelines. | | `text__gen__suggested__questions` | array | No | Up to 4 suggested prompts shown to users. Example: ['Write a summary', 'Create a report'] | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Box Sign Request **Slug:** `BOX_CREATE_BOX_SIGN_REQUEST` Creates a Box Sign request to send documents for electronic signing. Prepares documents and sends signature requests to signers via email. Signers do not need Box accounts. Supports up to 10 files, 35 signers, sequential signing order, templates, and custom redirect URLs. Requires Box Sign feature enabled and sign_requests.readwrite scope. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | Name of the signature request. Used for identification purposes. | | `signers` | array | Yes | List of signers for the signature request. At least one signer required, maximum 35 signers. | | `days_valid` | integer | No | Number of days (0-730) until the signature request automatically expires. No expiration if not set. | | `external_id` | string | No | External reference ID for tracking the signature request in your system. | | `template_id` | string | No | ID of a Box Sign template to use. When provided, template settings are applied to the request. | | `prefill_tags` | array | No | List of tags to pre-populate in the document before sending to signers. | | `redirect_url` | string | No | Global URL to redirect all signers to after successfully signing. | | `source_files` | array | Yes | List of files to be signed. At least one file required, maximum 10 files. All file types are converted to PDF. | | `email_message` | string | No | Custom message in the signature request email. Supports limited HTML tags: a, abbr, b, blockquote, code, em, i, ul, li, ol, strong. | | `email_subject` | string | No | Custom subject line for the signature request email sent to signers. | | `parent_folder` | object | No | Destination folder for signed documents. Cannot be the root folder (id='0'). | | `signature_color` | string ("blue" | "black" | "red") | No | Color to use for the signature | | `external_system_name` | string | No | Name of the external system for the signing log reference. | | `are_reminders_enabled` | boolean | No | Whether to send automatic reminders on days 3, 8, 13, and 18 to outstanding signers. | | `declined_redirect_url` | string | No | Global URL to redirect signers to if they decline to sign. | | `are_text_signatures_enabled` | boolean | No | Whether signers can use typed text as their signature (default: true). | | `is_document_preparation_needed` | boolean | No | If true, returns a prepare_url for completing document preparation in the Box UI before sending. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create box skill cards on file **Slug:** `BOX_CREATE_BOX_SKILL_CARDS_ON_FILE` Applies one or more Box Skills metadata cards to a file. NOTE: This action creates NEW Box Skill cards on a file. If Box Skill cards already exist on the file, this action will fail with a 409 Conflict error. In that case: - Use 'remove_box_skill_cards_from_file' to delete existing cards first, then create new ones, OR - Use 'update_all_box_skill_cards_on_file' to overwrite all existing cards #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `cards` | array | Yes | A list of Box Skill cards to apply to this file. Each card must include: 'type' (always 'skill_card'), 'skill_card_type' (one of: 'keyword', 'transcript', 'timeline', 'status'), 'skill' (object with 'type': 'service' and 'id'), 'invocation' (object with 'type': 'skill_invocation' and 'id'), and 'skill_card_title' (object with 'code' and 'message'). Additional fields depend on card type: keyword cards need 'entries' array with 'text' fields; transcript cards need 'entries' with 'text' and 'appears' (array of start/end timestamps) plus optional 'duration'; timeline cards need 'entries' with 'text', 'appears', and optional 'image_url' plus 'duration'; status cards need 'status' object with 'code' and 'message'. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Note: This file must NOT have existing Box Skill cards metadata, otherwise a 409 Conflict error will occur. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create user exemption from collaboration domain restrictions **Slug:** `BOX_CREATE_COLLAB_EXEMPTION` Exempts a specific user from the enterprise's collaboration domain restrictions. This allows the specified user to collaborate with external parties from any domain, bypassing the enterprise's allowed collaboration domain list. PREREQUISITES: - The enterprise MUST have at least one allowed collaboration domain configured. Use 'Add domain to list of allowed collaboration domains' first if needed. - The user must not already have an exemption (returns 409 Conflict if exists). - Requires enterprise admin privileges with 'manage_users' scope. COMMON ERRORS: - 409 Conflict: User already exempt OR no whitelisted domains exist for enterprise. - 403 Forbidden: Insufficient permissions to manage user exemptions. - 404 Not Found: The specified user ID does not exist. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `user__id` | string | Yes | The unique identifier (ID) of the Box user to exempt from collaboration domain restrictions. This allows the specified user to collaborate with external parties regardless of the enterprise's allowed domain list. Example: '23522323' | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create collaboration **Slug:** `BOX_CREATE_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, 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`. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `role` | string ("co-owner" | "editor" | "previewer" | "previewer uploader" | "uploader" | "viewer" | "viewer uploader") | Yes | The level of access granted. Valid values are: 'editor' (full read/write access), 'viewer' (read-only access), 'previewer' (preview-only), 'uploader' (upload-only), 'previewer uploader' (preview and upload), 'viewer uploader' (view and upload), or 'co-owner' (full access including sharing). | | `fields` | array | No | 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. | | `notify` | boolean | No | Determines if users should receive email notification for the action performed. | | `item__id` | string | No | The unique ID of the file or folder to grant access to. Required for creating a new collaboration. You can find this ID in the Box web interface URL or from other API responses. | | `expires_at` | string | No | 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. | | `item__type` | string ("file" | "folder") | No | The type of the item that this collaboration will be granted access to. Must be either 'file' or 'folder'. Required for creating a new collaboration. | | `can_view_path` | boolean | No | 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. | | `is_access_only` | boolean | No | 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. | | `accessible__by__id` | string | No | The Box user ID or group ID to invite. Either this field or 'accessible_by_login' must be provided (not both). Use this when you know the exact Box user/group ID. | | `accessible__by__type` | string ("group" | "user") | No | The type of collaborator to invite. Must be either 'user' or 'group'. Required. Use 'user' when inviting an individual (by email or user ID), or 'group' when sharing with a Box group. | | `accessible__by__login` | string | No | The email address of the user to invite as a collaborator. Either this field or 'accessible_by_id' must be provided (not both). Use this for user invitations when you have the email address but not the Box user ID. Not applicable for groups. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create comment **Slug:** `BOX_CREATE_COMMENT` Adds a comment by the user to a specific file, or as a reply to an other comment. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | 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. | | `message` | string | No | The text of the comment. Required unless `tagged_message` is provided. To mention a user, use `tagged_message` instead. | | `item__id` | string | Yes | The ID of the item to attach the comment to. This can be a file ID or a comment ID (when replying to a comment). | | `item__type` | string ("comment" | "file") | Yes | The type of item this comment will be placed on. Use 'file' to comment on a file, or 'comment' to reply to an existing comment. | | `tagged_message` | string | No | The text of the comment with user mentions. Use the format `@[user_id:name]` to mention a user, which sends them an email notification. The `user_id` is the target user's ID, and `name` is a display phrase that links to the user's profile in Box UI. Either `message` or `tagged_message` must be provided, but not both. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create email alias **Slug:** `BOX_CREATE_EMAIL_ALIAS` Adds a new email alias to a user account. The email domain must be registered to your enterprise. Returns the newly created email alias object with id, type, email, and is_confirmed fields. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `email` | string | Yes | The email address to add to the account as an alias. Note: The domain of the email alias must be registered to your enterprise. See the domain verification guide (https://support.box.com/hc/en-us/articles/4408619650579-Domain-Verification) for steps to add a new domain. | | `user_id` | string | Yes | The ID of the user. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create folder **Slug:** `BOX_CREATE_FOLDER` Creates a new empty folder within the specified parent folder. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | The name for the new folder. There are some restrictions to the file name. Names containing non-printable ASCII characters, forward and backward slashes (`/`, ``), as well as names with trailing spaces are prohibited. Additionally, the names `.` and `..` are not allowed either. | | `fields` | string | No | A comma-separated list of attributes to include in the response (e.g., 'id,name,created_at'). When specified, only the requested fields plus mini representation fields are returned. Common fields: id, type, name, description, size, created_at, modified_at, path_collection, created_by, modified_by, owned_by, shared_link, parent, item_status, tags, has_collaborations. | | `parent__id` | string | No | The ID of the parent folder where the new folder will be created. Use '0' for the root folder (All Files). Example: '123456789'. | | `sync_state` | string ("not_synced" | "partially_synced" | "synced") | No | Specifies whether a folder should be synced to a user"s device or not. This is used by Box Sync (discontinued) and is not used by Box Drive. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create folder lock **Slug:** `BOX_CREATE_FOLDER_LOCK` Creates a folder lock on a folder, preventing it from being moved and/or deleted. You must be authenticated as the owner or co-owner of the folder to use this endpoint. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder__id` | string | No | The ID of the folder. | | `folder__type` | string | No | The content type the lock is being applied to. Only `folder` is supported. | | `locked__operations__move` | boolean | No | Whether moving the folder should be locked. | | `locked__operations__delete` | boolean | No | Whether deleting the folder should be locked. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create group **Slug:** `BOX_CREATE_GROUP` Creates a new group of users in an enterprise. Only users with admin permissions can create new groups. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | The name of the new group to be created. This name must be unique within the enterprise. | | `fields` | array | No | A list of additional attributes to include in the response. Provide as a list of strings, e.g. ['description', 'provenance', 'invitability_level']. Available fields: 'id', 'name', 'description', 'provenance', 'external_sync_identifier', 'invitability_level', 'member_viewability_level', 'created_at', 'modified_at', 'permissions'. If specified, only the mini representation fields plus the requested fields are returned. | | `provenance` | string | No | 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. | | `description` | string | No | A human readable description of the group. | | `invitability_level` | string ("admins_and_members" | "admins_only" | "all_managed_users") | No | 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. | | `external_sync_identifier` | string | No | 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. | | `member_viewability_level` | string ("admins_and_members" | "admins_only" | "all_managed_users") | No | 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 | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create legal hold policy **Slug:** `BOX_CREATE_LEGAL_HOLD_POLICY` Create a new legal hold policy in Box. Legal hold policies are used to prevent permanent deletion of content during ongoing litigation. Once created, the policy can be assigned to specific users, folders, or files. IMPORTANT: Either `is_ongoing` must be set to true, OR both `filter_started_at` and `filter_ended_at` must be provided. The policy name must be unique within the enterprise. Requires Box Governance add-on (Enterprise plan with legal hold feature enabled). #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `is_ongoing` | boolean | No | Whether new assignments under this policy should continue applying to files even after initialization. If true, the policy will apply to any new file versions uploaded by assigned users even after the initial assignment. Required if no filter dates are set. Must be false if filter dates are provided. | | `description` | string | No | A description for the policy. Max 500 characters. | | `policy_name` | string | Yes | The name of the policy. Must be unique within the enterprise. Max 254 characters. | | `filter_ended_at` | string | No | The filter end date in ISO 8601 format (e.g., '2024-12-31T23:59:59-08:00'). When applied using custodian legal hold assignments, it will only apply to file versions created or uploaded inside the date range. Folder and file assignment types will ignore the date filter. Required if `is_ongoing` is set to `false`. | | `filter_started_at` | string | No | The filter start date in ISO 8601 format (e.g., '2024-01-01T00:00:00-08:00'). When applied using custodian legal hold assignments, it will only apply to file versions created or uploaded inside the date range. Folder and file assignment types will ignore the date filter. Required if `is_ongoing` is set to `false`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create metadata cascade policy **Slug:** `BOX_CREATE_METADATA_CASCADE_POLICY` Creates a new metadata cascade policy that automatically applies a metadata template to all files and subfolders within a specified folder. Prerequisites: - A metadata instance must already be applied to the target folder before creating the cascade policy. - The target folder cannot be the root folder (ID '0'). - Enterprise admin must have enabled 'Cascading Folder Level Metadata' in Admin Console > Enterprise Settings > Content & Sharing. Common use case: After applying metadata to a folder, create a cascade policy to ensure all new items added to that folder automatically inherit the metadata. Returns: A MetadataCascadePolicy object with id, type, owner_enterprise, parent, scope, and templateKey fields. Error codes: - 400: Invalid format for scope, templateKey, or folder_id - 403: Policy cannot apply to restricted folders (e.g., root folder) - 404: Folder or template not found/inaccessible - 409: Duplicate policy already exists for this folder/template combination #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string ("enterprise" | "global") | Yes | The scope of the metadata template. Use 'global' for Box's built-in templates (e.g., 'global.properties'), or 'enterprise' for custom enterprise templates. The metadata instance with this scope must already exist on the target folder. | | `folder_id` | string | Yes | The unique identifier of the folder to apply the cascade policy to. IMPORTANT: This folder must already have a metadata instance of the targeted template applied to it before creating the cascade policy. The folder ID can be found in Box URLs (e.g., 'https://app.box.com/folder/123' has folder_id '123'). Note: Cannot be applied to the root folder (ID '0'). | | `templateKey` | string | Yes | The key identifying the metadata template. Common examples include 'properties' for the global.properties template. For enterprise templates, the key is often derived from the template's display name (e.g., 'Contract Template' becomes 'contractTemplate'). You can find template keys by listing templates for an enterprise or getting metadata instances on a file/folder. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create metadata instance on file **Slug:** `BOX_CREATE_METADATA_INSTANCE_ON_FILE` Applies an instance of a metadata template to a file. The metadata_fields parameter contains key-value pairs that match the fields defined in the template. In most cases only field keys present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair. Common error codes: - 409 (tuple_already_exists): A metadata instance of this template already exists on the file. - 404 (not_found): The file was not found or the user does not have access. - 404 (instance_tuple_not_found): The metadata template was not found. - 400 (schema_validation_failed): Invalid field key or value type for the template. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string | Yes | The scope of the metadata template. Use 'global' for global templates (like 'properties') or 'enterprise' for enterprise templates. For enterprise templates, the scope will be automatically converted to the enterprise ID format (e.g., 'enterprise_12345'). | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `template_key` | string | Yes | The name of the metadata template (templateKey). For example: 'properties' for the global.properties template, or a custom template key like 'testTemplate'. Use BOX_LIST_ALL_METADATA_TEMPLATES_FOR_ENTERPRISE or BOX_LIST_ALL_GLOBAL_METADATA_TEMPLATES to find available template keys. | | `metadata_fields` | object | No | A dictionary of metadata field key-value pairs to set on the file. The keys must match the field keys defined in the metadata template. For the 'global.properties' template, any key-value pairs can be used. Example: {'author': 'John', 'status': 'draft'}. For enum fields, provide the option key string. For multiSelect fields, provide a list of strings. For date fields, use ISO 8601 format (e.g., '2024-01-15T00:00:00Z'). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create metadata instance on folder **Slug:** `BOX_CREATE_METADATA_INSTANCE_ON_FOLDER` Applies an instance of a metadata template to a folder. In most cases only values that are present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair. To display the metadata template in the Box web app the enterprise needs to be configured to enable **Cascading Folder Level Metadata** for the user in the admin console. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string | Yes | The scope of the metadata template. Use 'global' for global templates or 'enterprise' for enterprise templates (will use the enterprise ID like 'enterprise_12345'). | | `metadata` | object | No | A dictionary of key-value pairs representing the metadata fields to apply. For the 'global.properties' template, any key-value pairs are accepted. For enterprise templates, keys must match the template's field names. Example: {'field1': 'value1', 'field2': 'value2'} | | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `template_key` | string | Yes | The name of the metadata template | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create metadata taxonomy **Slug:** `BOX_CREATE_METADATA_TAXONOMY` Tool to create a new metadata taxonomy in Box. Use when you need to set up a hierarchical classification system for organizing and categorizing metadata templates. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `key` | string | No | The taxonomy key. If not provided, it will be automatically generated from the displayName by converting to lowercase and replacing spaces and non-alphanumeric characters with underscores. Maximum length is 256 characters. Must match pattern ^[a-zA-Z_][-a-zA-Z0-9_]*$. | | `namespace` | string | Yes | The namespace of the metadata taxonomy to create. Must be in the format 'enterprise_{enterprise_id}' where enterprise_id is your Box enterprise ID. You can retrieve your enterprise ID from the /users/me endpoint with fields=enterprise. | | `displayName` | string | Yes | The display name of the taxonomy. This name will be visible in the Box web app and can be used to identify the taxonomy. Maximum length is 4096 characters. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create metadata taxonomy levels **Slug:** `BOX_CREATE_METADATA_TAXONOMY_LEVELS` Creates new hierarchical levels for a metadata taxonomy in Box. Use this to define the structure of your taxonomy by specifying levels like Continent -> Country -> City. Each level must have a unique level number starting from 1, with higher numbers representing deeper levels in the hierarchy. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `levels` | array | Yes | An array of taxonomy levels to create. Each level must have a unique level number (starting from 1), a display name, and optionally a description. Levels should be ordered hierarchically. | | `namespace` | string | Yes | The namespace of the metadata taxonomy. For enterprise taxonomies, this is typically in the format 'enterprise_' (e.g., 'enterprise_123456'). | | `taxonomy_key` | string | Yes | The unique key identifier of the metadata taxonomy to which the levels will be added. This key was assigned when the taxonomy was created. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create metadata taxonomy node **Slug:** `BOX_CREATE_METADATA_TAXONOMY_NODE` Tool to create a new metadata taxonomy node within a specified taxonomy. Use when you need to add a new classification or category to an existing metadata taxonomy hierarchy. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `level` | integer | Yes | The level of the taxonomy node in the hierarchy. Root-level nodes have level 1, their children have level 2, and so on. Must be a positive integer. | | `parentId` | string | No | The identifier of the parent taxonomy node. Omit this field when creating root-level nodes (level 1). For child nodes, provide the UUID of the parent node. | | `namespace` | string | Yes | The namespace of the metadata taxonomy. Typically follows the format 'enterprise_{enterprise_id}' for enterprise taxonomies. For example: 'enterprise_1351007304'. | | `displayName` | string | Yes | The display name of the taxonomy node. This is the human-readable name that will be shown in the Box UI. For example: 'France', 'California', 'Engineering Department'. | | `taxonomy_key` | string | Yes | The key of the metadata taxonomy under which to create the node. This identifies the specific taxonomy within the namespace. For example: 'geography' or 'department'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create metadata template **Slug:** `BOX_CREATE_METADATA_TEMPLATE` Creates a new metadata template that can be applied to files and folders. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string | No | The scope of the metadata template to create. Must be set to 'enterprise' as applications cannot create global templates. Defaults to 'enterprise'. | | `fields` | array | No | An ordered list of template fields which are part of the template. Each field can be a regular text field, date field, number field, as well as a single or multi-select list. | | `hidden` | boolean | No | Defines if this template is visible in the Box web app UI, or if it is purely intended for usage through the API. | | `displayName` | string | Yes | The display name of the template. | | `templateKey` | string | No | A unique identifier for the template. This identifier needs to be unique across the enterprise for which the metadata template is being created. When not provided, the API will create a unique `templateKey` based on the value of the `displayName`. | | `copyInstanceOnItemCopy` | boolean | No | Whether or not to copy any metadata attached to a file or folder when it is copied. By default, metadata is not copied along with a file or folder when it is copied. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create retention policy **Slug:** `BOX_CREATE_RETENTION_POLICY` Creates a retention policy for managing content lifecycle in Box. Retention policies prevent permanent deletion of content for a specified duration. Once created, policies can be assigned to folders or the entire enterprise. Note: This endpoint requires the Box Governance add-on feature and the 'manage retention policies' scope enabled in your application. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `description` | string | No | The additional text description of the retention policy (max 500 characters). | | `policy_name` | string | Yes | The name for the retention policy. Must be unique within the enterprise. | | `policy_type` | string ("finite" | "indefinite") | Yes | The type of the retention policy. Use 'finite' when the retention duration is known upfront, or 'indefinite' when the retention duration is unknown. For finite policies, retention_length must be specified. | | `retention_type` | string ("modifiable" | "non_modifiable") | No | Retention type enum: controls if policy can be modified after creation. | | `retention_length` | integer | No | The number of days to retain content under this policy. Required when policy_type is 'finite'. Minimum value is 1 day. For 'indefinite' policies, this field should not be set. Specify as an integer (e.g., 30, 365, 2555). | | `disposition_action` | string ("permanently_delete" | "remove_retention") | Yes | The action to take when the retention policy expires. 'permanently_delete' will permanently delete the retained content. 'remove_retention' lifts the retention policy, allowing users to delete the content manually. | | `are_owners_notified` | boolean | No | Whether owners and co-owners of files are notified when the retention policy nears expiration. | | `can_owner_extend_retention` | boolean | No | Whether file owners are allowed to extend the retention period before it expires. | | `custom_notification_recipients` | array | No | A list of users to notify when the retention policy duration is about to end. Each user should be specified with at least their 'id' field. Example: [{'type': 'user', 'id': '12345678'}] | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create shield information barrier **Slug:** `BOX_CREATE_SHIELD_INFORMATION_BARRIER` Creates a shield information barrier to establish an "ethical wall" that separates individuals/groups within an enterprise and prevents confidential information sharing. Prerequisites: Box Shield add-on must be licensed and enabled. Admin-level permissions required. Only one barrier allowed per enterprise. NOT available in Shield trials. Workflow: 1) Get enterprise ID from /users/me, 2) Create barrier (starts in 'draft'), 3) Create segments and add users, 4) Define segment restrictions, 5) Enable barrier. Common errors: 400 (missing enterprise), 404 (Shield not enabled/invalid ID), 409 (barrier already exists). #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `enterprise__id` | string | Yes | The unique identifier of the enterprise where the shield information barrier will be created. This ID can be obtained from the GET /users/me endpoint (enterprise.id field). Example: '1351007304' | | `enterprise__type` | string | No | The type of the enterprise object. Must be 'enterprise'. This field has a sensible default and typically doesn't need to be changed. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create shield information barrier report **Slug:** `BOX_CREATE_SHIELD_INFORMATION_BARRIER_REPORT` Creates a shield information barrier report for a given barrier. Shield information barrier reports track the configuration status of information barriers in Box Shield. When created, reports start with status 'pending' and transition to 'done', 'error', or 'cancelled'. Note: Requires Box Shield enterprise add-on license. Returns 404 if Shield is not enabled for the enterprise. Returns 409 if a report is already being created. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `shield__information__barrier__id` | string | Yes | The ID of the shield information barrier to create a report for. Get this from BOX_LIST_SHIELD_INFORMATION_BARRIERS or BOX_CREATE_SHIELD_INFORMATION_BARRIER. | | `shield__information__barrier__type` | string ("shield_information_barrier") | No | The type of the shield information barrier resource. Must be 'shield_information_barrier'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create shield information barrier segment **Slug:** `BOX_CREATE_SHIELD_INFORMATION_BARRIER_SEGMENT` Creates a new shield information barrier segment for compliance and information isolation. Segments represent organizational divisions (e.g., Investment Banking, Research, Trading) that need to be isolated from each other for regulatory compliance. Each segment can have users assigned to it, and restrictions can be created to prevent collaboration between specific segments. Prerequisites: Box Shield license, existing barrier (create_shield_information_barrier), barrier in 'draft'/'pending' status. Returns 404 if Shield not enabled or barrier doesn't exist. Returns 409 if segment name already exists. Related: create_shield_information_barrier_segment_member, create_shield_information_barrier_segment_restriction, list_shield_information_barrier_segments #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | **Required**. The name of the segment to create (e.g., 'Investment Banking', 'Research Division', 'Trading Desk'). This name must be unique within the barrier and identifies the group of users for compliance isolation. | | `description` | string | No | Optional description explaining the segment's purpose and scope (e.g., 'Corporate division handling M&A advisory services and IPO underwriting'). Helps administrators understand the segment's business context. | | `shield__information__barrier__id` | string | Yes | **Required**. The unique ID of the shield information barrier to create the segment under. Obtain this from list_shield_information_barriers or create_shield_information_barrier actions. The barrier must be in 'draft' or 'pending' status to add segments. | | `shield__information__barrier__type` | string ("shield_information_barrier") | No | The type of the shield information barrier object. Must be 'shield_information_barrier'. This field has a sensible default and typically doesn't need to be explicitly provided. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create shield information barrier segment member **Slug:** `BOX_CREATE_SHIELD_INFORMATION_BARRIER_SEGMENT_MEMBER` Adds a Box user to a shield information barrier segment for compliance and information security. This assigns users to segments that restrict collaboration between departments (e.g., Investment Banking vs Research in financial institutions). Users can only belong to ONE segment at a time. Prerequisites: Box Shield license, existing barrier and segment, valid user ID. Returns 404 if Shield not enabled or resources don't exist. Related: create_shield_information_barrier_segment, list_shield_information_barrier_segment_members #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string ("shield_information_barrier_segment_member") | No | The type of the object. Must be 'shield_information_barrier_segment_member' if provided. This is an optional field that defaults to the correct value. | | `user__id` | string | Yes | **Required**. The ID of the Box user to add as a member of the segment. Obtain this from get_current_user, list_enterprise_users, or other user-related actions. The user must exist in the same enterprise. | | `user__type` | string ("user") | No | The type of the user object. Must be 'user'. This field has a sensible default value and typically doesn't need to be explicitly provided. | | `shield__information__barrier__id` | string | No | (Optional) The unique identifier for the shield information barrier. If not provided, the system will infer it from the segment. | | `shield__information__barrier__type` | string ("shield_information_barrier") | No | (Optional) The type of the shield information barrier object. Must be 'shield_information_barrier' if provided. | | `shield__information__barrier__segment__id` | string | Yes | **Required**. The unique ID of the shield information barrier segment to which the user will be added. Obtain this from list_shield_information_barrier_segments or create_shield_information_barrier_segment actions. A user can only belong to one segment. | | `shield__information__barrier__segment__type` | string ("shield_information_barrier_segment") | No | The type of the shield barrier segment object. Must be 'shield_information_barrier_segment'. This field has a sensible default and typically doesn't need to be provided. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create shield information barrier segment restriction **Slug:** `BOX_CREATE_SHIELD_INFORMATION_BARRIER_SEGMENT_RESTRICTION` Creates a ONE-WAY shield information barrier segment restriction preventing collaboration between members of two segments (e.g., Investment Banking cannot collaborate with Research). Prerequisites: - Box Shield add-on enabled (returns 404 if not available) - Admin privileges required - Both segments must exist in the same barrier Key details: - Creates ONE-WAY restriction. For bidirectional, call twice with swapped segment IDs - shield_information_barrier parameter is optional (inferred from segments) - Use create_shield_information_barrier_segment to create segments first - Common for regulatory compliance and ethical walls Workflow: 1) Create barrier 2) Create segments 3) Create restrictions 4) Add members to segments #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string | No | The type of the restriction object. Must be 'shield_information_barrier_segment_restriction'. | | `restricted__segment__id` | string | Yes | The ID of the segment to be restricted. Members of the requesting segment cannot collaborate with members of this restricted segment. | | `restricted__segment__type` | string | No | The type of the restricted segment. Must be 'shield_information_barrier_segment'. | | `shield__information__barrier__id` | string | No | Optional: The unique identifier (ID) of the parent shield information barrier. If not provided, Box will infer it from the segment IDs. Obtain this from the list or create shield information barrier endpoints. | | `shield__information__barrier__type` | string | No | The type of the shield information barrier. Must be 'shield_information_barrier'. | | `shield__information__barrier__segment__id` | string | Yes | The ID of the requesting segment that initiates the restriction. This segment's members will be restricted from collaborating with the restricted segment. | | `shield__information__barrier__segment__type` | string | No | The type of the requesting segment. Must be 'shield_information_barrier_segment'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create slack integration mapping **Slug:** `BOX_CREATE_SLACK_INTEGRATION_MAPPING` Creates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) by mapping a Slack channel to a Box item. You need Admin or Co-Admin role to use this endpoint. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `options` | object | No | Configuration options for the integration mapping. | | `box_item` | object | Yes | The Box folder to map to a Slack channel. The service account must be an owner or co-owner of this folder. | | `partner_item` | object | Yes | The Slack channel information to map to a Box folder. Requires either slack_workspace_id or slack_org_id depending on how Box for Slack is installed. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create task **Slug:** `BOX_CREATE_TASK` Creates a single task on a file. This task is not assigned to any user and will need to be assigned separately. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string ("complete" | "review") | No | The type of task to create: 'review' creates an approval task that can be approved or rejected, 'complete' creates a general task that can be marked as complete. Default: 'review' | | `due_at` | string | No | The date and time when the task is due in ISO 8601 format (e.g., '2026-12-31T23:59:59Z'). If not provided, the task has no due date. | | `message` | string | No | Optional message or instructions for the task assignee | | `item__id` | string | No | The unique identifier of the file to create the task on | | `item__type` | string ("file") | No | The type of the item, must be 'file' | | `completion_rule` | string ("all_assignees" | "any_assignee") | No | Determines how many assignees must complete the task: 'all_assignees' (default) requires all assignees to complete it, 'any_assignee' requires only one assignee to complete it | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create Teams integration mapping **Slug:** `BOX_CREATE_TEAMS_INTEGRATION_MAPPING` Creates a Microsoft Teams integration mapping that links a Teams channel or team to a Box folder. Once mapped, files shared in the Teams channel are automatically stored in the linked Box folder. Requires Admin/Co-Admin role and the `manage_enterprise_properties` scope. **Prerequisites:** - Box for Teams must be installed in the Microsoft Teams workspace - The Box folder must be owned by the enterprise and not already mapped See: https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `box_item` | object | Yes | The Box folder to link with the Microsoft Teams channel/team. Files shared in the mapped Teams location will be stored in this Box folder. | | `partner_item` | object | Yes | The Microsoft Teams channel or team information to create a mapping for. Requires the channel/team ID, team ID, and tenant ID from your Microsoft 365 environment. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create terms of service **Slug:** `BOX_CREATE_TERMS_OF_SERVICE` Creates a terms of service for a given enterprise and type of user. This action requires enterprise admin permissions with 'Edit settings for your company' enabled. The Terms of Service feature must also be enabled for the enterprise in the Box Admin Console. Box supports two types of Terms of Service: - 'managed': Applied to the enterprise's own users - 'external': Applied to external collaborators from other enterprises #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `text` | string | Yes | The terms of service text to display to users. The text can be set to empty if the `status` is set to `disabled`. | | `status` | string ("disabled" | "enabled") | Yes | Whether this terms of service is active. Use 'enabled' to activate or 'disabled' to deactivate. | | `tos_type` | string ("external" | "managed") | Yes | The type of user to set the terms of service for. Use 'managed' for the enterprise's own users, or 'external' for users from other enterprises that collaborate on the enterprise's data. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create terms of service status for new user **Slug:** `BOX_CREATE_TERMS_OF_SERVICE_STATUS_FOR_NEW_USER` Creates a terms of service status record for a user who has not previously accepted or rejected the terms. This action records whether a user has accepted or rejected a specific terms of service. Use this for users who are encountering the terms of service for the first time. For users who have previously accepted or rejected terms, use update_terms_of_service_status_for_existing_user instead. Prerequisites: - The Terms of Service feature must be enabled for the enterprise in the Box Admin Console - A terms of service must exist (created via create_terms_of_service) - The user must not already have a status record for this terms of service Note: If a status already exists for the user and terms of service combination, the API will return an error. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tos__id` | string | Yes | The unique identifier (ID) of the terms of service to set the user's status for. Obtain this ID from the list_terms_of_services action. | | `user__id` | string | Yes | The unique identifier (ID) of the user to set the terms of service status for. Obtain this ID from list_enterprise_users or get_current_user actions. | | `tos__type` | string ("terms_of_service") | No | The type of the terms of service object. Must be 'terms_of_service'. | | `user__type` | string ("user") | No | The type of the user object. Must be 'user'. | | `is_accepted` | boolean | Yes | Whether the user has accepted the terms of service. Set to true if the user has accepted, false if they have rejected or not yet accepted. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create upload session **Slug:** `BOX_CREATE_UPLOAD_SESSION` Creates an upload session for chunked upload of large files (20MB+). This is the first step in Box's chunked upload process. After creating the session, you must: (1) upload file chunks using the upload_part endpoint, (2) commit the session using the commit endpoint to finalize the file. The session expires after 7 days. Use this for files 20MB or larger. For smaller files, use the regular upload endpoint instead. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_name` | string | Yes | The name for the new file including extension. Must not contain forward or backward slashes, non-printable ASCII characters, or trailing spaces. Cannot be '.' or '..'. Example: 'large_video.mp4' or 'presentation.pptx' | | `file_size` | integer | Yes | The total size of the file in bytes. Must be at least 20MB (20971520 bytes) since chunked uploads are only for large files. Maximum depends on account storage limits. Example: 104857600 (100MB) | | `folder_id` | string | Yes | The ID of the folder where the file will be uploaded. Use '0' for the root folder (All Files), or provide a specific folder ID. Example: '123456789' or '0' | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create upload session for existing file **Slug:** `BOX_CREATE_UPLOAD_SESSION_FOR_EXISTING_FILE` Creates an upload session for uploading a new version of an existing file using chunked upload. Use this for files larger than 20MB. The session provides endpoints for uploading file parts, committing the upload, and checking status. Returns session info including part_size, total_parts, and session_endpoints for managing the chunked upload process. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `file_name` | string | No | The optional new name for the uploaded file version. If not provided, the original file name is retained. | | `file_size` | integer | Yes | The total number of bytes of the file to be uploaded. Must be at least 20000000 bytes (20 MB) for chunked upload sessions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create user **Slug:** `BOX_CREATE_USER` Creates a new managed user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | The name of the user | | `role` | string ("coadmin" | "user") | No | The user’s enterprise role | | `login` | string | No | The email address the user uses to log in. Required for standard users, but optional when `is_platform_access_only` is set to `true`. | | `phone` | string | No | The user’s phone number | | `fields` | array | No | List of attributes to include in the response (e.g., ['id', 'name', 'login', 'role']). This can be used to request fields that are not normally returned in a standard response. Note: Specifying this parameter will return only the mini representation fields plus the explicitly requested fields, not the standard full response. | | `status` | string ("active" | "cannot_delete_edit" | "cannot_delete_edit_upload" | "inactive") | No | The user's account status (active, inactive, cannot_delete_edit, or cannot_delete_edit_upload) | | `address` | string | No | The user’s address | | `language` | string | No | The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format. | | `timezone` | string | No | The user's timezone (e.g., 'America/Los_Angeles', 'America/New_York') | | `job_title` | string | No | The user’s job title | | `space_amount` | integer | No | The user’s total available space in bytes. Set this to `-1` to indicate unlimited storage. | | `tracking_codes` | array | No | Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used. | | `is_sync_enabled` | boolean | No | Whether the user can use Box Sync | | `external_app_user_id` | string | No | An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users. | | `can_see_managed_users` | boolean | No | Whether the user can see other enterprise users in their contact list | | `is_platform_access_only` | boolean | No | Specifies that the user is an app user. | | `is_exempt_from_device_limits` | boolean | No | Whether to exempt the user from enterprise device limits | | `is_external_collab_restricted` | boolean | No | Whether the user is allowed to collaborate with users outside their enterprise | | `is_exempt_from_login_verification` | boolean | No | Whether the user must use two-factor authentication | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create user invite **Slug:** `BOX_CREATE_USER_INVITE` Invites an existing external user to join an enterprise. The existing user can not be part of another enterprise and must already have a Box account. Once invited, the user will receive an email and are prompted to accept the invitation within the Box web application. This method requires the "Manage An Enterprise" scope enabled for the application, which can be enabled within the developer console. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | 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. | | `enterprise__id` | string | Yes | The unique identifier (ID) of the enterprise to invite the user to. You can obtain this ID by querying the current user's profile with the 'enterprise' field requested (e.g., GET /users/me?fields=enterprise). | | `actionable__by__login` | string | Yes | The email address (login) of the external user to invite. The user must already have an existing Box account and cannot be part of another enterprise. Example: 'john@example.com' | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create webhook **Slug:** `BOX_CREATE_WEBHOOK` Creates a webhook to monitor a file or folder for specific events. Webhooks allow you to receive notifications at a specified URL when events occur on Box content. When an event triggers, Box sends an HTTP POST request to your specified address with details about the event. Requirements: - The notification URL must use HTTPS on port 443 - The URL must respond with HTTP 200-299 within 30 seconds - Requires 'Manage Webhooks' scope enabled for the application Note: Folder webhooks cascade to sub-folders automatically. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `address` | string | Yes | The HTTPS URL that will receive webhook notifications. Must use port 443 and return HTTP 200-299 within 30 seconds. | | `triggers` | array | Yes | List of event triggers that will fire the webhook (e.g., FILE.UPLOADED, FOLDER.CREATED). See TriggersEnm0 for all options. | | `target__id` | string | Yes | The ID of the file or folder to monitor for events. Required. | | `target__type` | string ("file" | "folder") | Yes | The type of item to monitor: 'file' or 'folder'. Required. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create web link **Slug:** `BOX_CREATE_WEB_LINK` Creates a web link object within a folder. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `url` | string | Yes | The URL that this web link links to. Must start with `"http://"` or `"https://"`. | | `name` | string | No | Name of the web link. Defaults to the URL if not set. | | `parent__id` | string | No | The ID of parent folder | | `description` | string | No | Description of the web link. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create zip download **Slug:** `BOX_CREATE_ZIP_DOWNLOAD` Creates a request to download multiple files and folders as a single `zip` archive file. This API does not return the archive but instead performs all the checks to ensure that the user has access to all the items, and then returns a `download_url` and a `status_url` that can be used to download the archive. The limit for an archive is either the Account's upload limit or 10,000 files, whichever is met first. **Note**: Downloading a large file can be affected by various factors such as distance, network latency, bandwidth, and congestion, as well as packet loss ratio and current server load. For these reasons we recommend that a maximum ZIP archive total size does not exceed 25GB. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `items` | array | Yes | A list of items to add to the `zip` archive. These can be folders or files. | | `download_file_name` | string | No | The optional name of the `zip` archive. This name will be appended by the `.zip` file extension, for example `January Financials.zip`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete AI Agent **Slug:** `BOX_DELETE_AI_AGENT` Permanently deletes a custom AI agent from Box AI Studio. This action removes the specified AI agent and all its configuration, including any custom instructions and capability settings. This operation cannot be undone. Note: This action requires the 'Manage AI' scope to be enabled for the Box application. The authenticated user must have appropriate permissions to delete AI agents. Common error responses: - 403 Forbidden: Insufficient permissions or 'Manage AI' scope not enabled - 404 Not Found: The specified agent_id does not exist #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `agent_id` | string | Yes | The unique identifier of the AI agent to delete. This ID is returned when creating an AI agent or can be retrieved by listing AI agents. Example: '1234567890'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove domain from list of allowed collaboration domains **Slug:** `BOX_DELETE_ALLOWED_COLLABORATION_DOMAIN` Removes a domain from the list of allowed collaboration domains (whitelist) within your enterprise. This action deletes a specific collaboration whitelist entry, preventing users from that domain from collaborating on your enterprise's content (or vice versa, depending on the original direction). **Requirements:** - Enterprise admin privileges - The 'manage_enterprise_properties' scope - External collaboration allowlisting must be enabled for your enterprise (part of the Governance package) **Usage:** Provide the collaboration_whitelist_entry_id of the domain entry you want to remove. You can obtain this ID from the 'Add domain' or 'List allowed collaboration domains' actions. **Response:** Returns 204 No Content on successful deletion. This operation is idempotent - deleting an already deleted entry will still return success. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `collaboration_whitelist_entry_id` | string | Yes | The unique identifier (ID) of the collaboration whitelist entry to remove. This ID can be obtained from the 'Add domain to list of allowed collaboration domains' or 'List allowed collaboration domains' actions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete shield information barrier segment restriction by id **Slug:** `BOX_DELETE_BARRIER_RESTRICTION` Deletes a shield information barrier segment restriction by its unique ID. Shield information barrier segment restrictions define which segments cannot communicate with each other. When a restriction is deleted, users in the previously restricted segments will be able to collaborate again. **Important Notes:** - This operation is destructive and cannot be undone - Returns HTTP 204 (No Content) with empty response body on success - Requires Box Shield add-on with information barriers enabled - Idempotent: Deleting a non-existent restriction returns 404 (not an error state) - Requires admin privileges **Prerequisites:** - Box Shield add-on enabled (returns 404 if not available) - Valid segment restriction ID from create or list operations #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `shield_information_barrier_segment_restriction_id` | string | Yes | The unique identifier of the shield information barrier segment restriction to delete. Obtain this ID from BOX_CREATE_SHIELD_INFORMATION_BARRIER_SEGMENT_RESTRICTION or BOX_LIST_SHIELD_INFORMATION_BARRIER_SEGMENT_RESTRICTIONS actions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove box skill cards from file **Slug:** `BOX_DELETE_BOX_SKILL_CARDS_FROM_FILE` Removes any Box Skills cards metadata from a file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove collaboration **Slug:** `BOX_DELETE_COLLABORATION` Removes a collaboration from a file or folder, revoking the collaborator's access. A collaboration in Box represents shared access granted to a user or group on a file or folder. Removing a collaboration will: - Revoke the collaborator's access to the item immediately - Remove the item from the collaborator's "Shared with Me" view - Cancel any pending invitations if the collaboration was not yet accepted This action is permanent and cannot be undone. To restore access, you would need to create a new collaboration. Returns HTTP 204 (No Content) on successful deletion. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `collaboration_id` | string | Yes | The unique identifier of the collaboration to remove. A collaboration represents shared access granted to a user or group on a file or folder. You can obtain collaboration IDs by listing collaborations on a folder (using list_folder_collaborations) or file (using list_file_collaborations), or from the response when creating a collaboration. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove comment **Slug:** `BOX_DELETE_COMMENT` Permanently deletes a comment from a file or folder in Box. This action removes a comment that was previously added to a Box item. Once deleted, the comment cannot be recovered. The operation returns HTTP 204 (No Content) on success. If the comment does not exist or has already been deleted, a 404 error is returned. Note: Only the user who created the comment or an admin can delete it. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `comment_id` | string | Yes | The unique identifier of the comment to delete. This can be obtained from the response when creating a comment (BOX_CREATE_COMMENT) or by listing comments on a file (BOX_LIST_FILE_COMMENTS). Example: '695212827'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove device pin **Slug:** `BOX_DELETE_DEVICE_PIN` Deletes an individual device pin from the enterprise. Device pins are created when users access Box from mobile or desktop devices that support device pinning. Removing a device pin will require the user to re-authenticate on that device. This endpoint requires admin privileges and the 'manage_enterprise_properties' scope. On successful deletion, returns HTTP 204 No Content. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `device_pinner_id` | string | Yes | The unique identifier of the device pin to remove. Device pin IDs can be obtained from the 'List enterprise device pins' endpoint. Example: '2324234'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove email alias **Slug:** `BOX_DELETE_EMAIL_ALIAS` Removes an email alias from a user. This endpoint permanently deletes an email alias associated with a user account. Note: You cannot remove a user's primary email address. To change the primary email, you must first create a new alias, set it as primary, then remove the old one. Returns HTTP 204 (No Content) on success with an empty response body. Returns HTTP 404 if the user or email alias is not found. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `user_id` | string | Yes | The ID of the user whose email alias will be removed. Can be obtained from BOX_GET_CURRENT_USER or BOX_LIST_ENTERPRISE_USERS. | | `email_alias_id` | string | Yes | The ID of the email alias to remove. Can be obtained from BOX_LIST_USER_S_EMAIL_ALIASES or BOX_CREATE_EMAIL_ALIAS response. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete file **Slug:** `BOX_DELETE_FILE` Deletes a file from Box by moving it to trash or permanently (based on enterprise settings). Use the `if_match` parameter with the file's ETag for safe concurrent operations. To permanently delete a trashed file, use the 'Permanently remove file' action instead. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier of the file to delete. You can find the file ID by viewing the file in Box web app and copying from the URL (e.g., for `https://*.app.box.com/files/123` the file_id is `123`). | | `if_match` | string | No | Optional ETag value for optimistic concurrency control. Pass the file's last observed `etag` value to ensure the file hasn't been modified since you last retrieved it. If the file has changed, the request fails with HTTP 412 Precondition Failed. You can get the etag from the file's metadata or from a previous API response. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Permanently remove file **Slug:** `BOX_DELETE_FILE_PERMANENTLY` Permanently deletes a file from the trash. This action is irreversible and cannot be undone. The file must already be in the trash before it can be permanently removed. To move a file to trash first, use the 'Delete file' action. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier of the trashed file to permanently delete. The file must already be in the trash (deleted via 'Delete file' action). You can find the file ID by listing trashed items or from the Box web app URL (e.g., for `https://*.app.box.com/files/123` the file_id is `123`). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete file request **Slug:** `BOX_DELETE_FILE_REQUEST` Deletes a file request permanently. File requests allow external users to upload files to a specific folder without needing a Box account. This action permanently deletes a file request. IMPORTANT LIMITATION: File request IDs cannot be discovered via API - they can only be obtained from the Box web application. To find a file_request_id: 1. Navigate to Box web UI (https://app.box.com) 2. Go to the folder containing the file request 3. Open the file request settings 4. Copy the ID from the URL (e.g., https://*.app.box.com/filerequest/123 → ID is "123") **Response:** Returns HTTP 204 No Content on success (empty response body). **Common Use Cases:** - Removing file requests that are no longer needed - Cleaning up expired or inactive file requests - Managing file request lifecycle programmatically **Note:** This operation is permanent and cannot be undone. The file request will be deleted immediately, but any files that were already uploaded through the file request will remain in the destination folder. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_request_id` | string | Yes | The unique identifier of the file request to delete. IMPORTANT: File request IDs can ONLY be obtained from the Box web application URL - there is no API to list file requests. To find a file_request_id: 1. Navigate to Box web UI (https://app.box.com) 2. Go to the folder containing the file request 3. Open the file request settings 4. Copy the ID from the URL (e.g., https://*.app.box.com/filerequest/123 → ID is '123') | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove file version **Slug:** `BOX_DELETE_FILE_VERSION` Move a file version to the trash. Versions are only tracked for Box users with premium accounts. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `file_version_id` | string | Yes | The unique identifier of the file version to remove. Version IDs can be obtained by using the 'List all file versions' action with the file_id. Note: The current file version cannot be deleted - only previous versions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete folder **Slug:** `BOX_DELETE_FOLDER` Deletes a folder, either permanently or by moving it to the trash. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `recursive` | boolean | No | Delete a folder that is not empty by recursively deleting the folder and all of its content. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete folder lock **Slug:** `BOX_DELETE_FOLDER_LOCK` Deletes a folder lock on a given folder, removing restrictions on move and delete operations. You must be authenticated as the owner or co-owner of the folder to use this endpoint. This action removes a lock that was previously applied to prevent a folder from being moved or deleted. Once the lock is removed, the folder can be moved, transferred to another owner, or deleted normally. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_lock_id` | string | Yes | The unique identifier of the folder lock to delete. You can obtain this ID by calling the 'list_folder_locks' action with a folder_id, or from the response when creating a folder lock. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Permanently remove folder **Slug:** `BOX_DELETE_FOLDER_PERMANENTLY` Permanently deletes a folder that is in the trash. This action cannot be undone. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove group **Slug:** `BOX_DELETE_GROUP` Permanently deletes a group. Only users with admin-level permissions will be able to use this API. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `group_id` | string | Yes | The unique identifier of the group to delete. This is a numeric ID string (e.g., '57645') that can be obtained from BOX_LIST_GROUPS_FOR_ENTERPRISE or BOX_CREATE_GROUP responses. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove legal hold policy **Slug:** `BOX_DELETE_LEGAL_HOLD_POLICY` Permanently delete an existing legal hold policy from Box. This is an asynchronous operation - the policy deletion is initiated but may not complete immediately. A successful response (HTTP 202) indicates the deletion has started. The policy cannot be recovered after deletion. Note: Legal Hold is an enterprise feature that must be enabled for your Box account. Requires 'manage_legal_holds' scope. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `legal_hold_policy_id` | string | Yes | The unique identifier (ID) of the legal hold policy to permanently delete. This is a string containing the policy ID (e.g., '324432', '11111'). You can obtain policy IDs by using BOX_LIST_ALL_LEGAL_HOLD_POLICIES to list existing policies, or from the response when creating a policy with BOX_CREATE_LEGAL_HOLD_POLICY. Warning: Deletion is permanent and cannot be undone. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove metadata cascade policy **Slug:** `BOX_DELETE_METADATA_CASCADE_POLICY` Permanently deletes a metadata cascade policy from a folder. When deleted, existing metadata on files/subfolders remains, but new items will no longer automatically inherit the template. Prerequisites: Requires 'manage_managed_metadata' scope and admin permissions. Returns: HTTP 204 No Content on success (empty response body). Operation is idempotent. Error codes: - 400: Invalid policy ID format - 404: Policy not found or folder inaccessible - 403: Insufficient permissions Related: BOX_CREATE_METADATA_CASCADE_POLICY, BOX_LIST_METADATA_CASCADE_POLICIES #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `metadata_cascade_policy_id` | string | Yes | The unique identifier of the metadata cascade policy to delete. This ID can be obtained from the response of BOX_CREATE_METADATA_CASCADE_POLICY or BOX_LIST_METADATA_CASCADE_POLICIES actions. Example format: 'MzYzNTE5MTQzNDQwI2UxMzUxMDA3MzA0I3Rlc3RDYXNjYWRlUG9saWN5VGVtcGxhdGUtMzYxZWFmOTYtYmJlMy00YjhlLWEwNTctMmY2NjM5MTU1Yjlj' | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove metadata instance from file **Slug:** `BOX_DELETE_METADATA_INSTANCE_FROM_FILE` Removes a metadata instance from a file. Deletes all metadata associated with a specific template from a file. This operation cannot be undone. The metadata template itself is not deleted, only the instance of metadata applied to this specific file. Returns a 204 No Content response on success. Returns 404 if the metadata instance doesn't exist on the file or if the file is not found. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string ("enterprise" | "global") | Yes | The scope of the metadata template. Use 'global' for Box-provided templates available to all enterprises, or 'enterprise' for templates created within your enterprise. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `template_key` | string | Yes | The key (identifier) of the metadata template to remove from the file. For example, 'properties' for the standard Box properties template, or a custom template key for enterprise templates. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove metadata instance from folder **Slug:** `BOX_DELETE_METADATA_INSTANCE_FROM_FOLDER` Remove a metadata instance from a folder. Deletes a specific metadata template instance that has been applied to a folder. This operation is idempotent and will return a 404 error if the metadata instance doesn't exist. Returns HTTP 204 No Content on successful deletion. Note: This only removes the metadata instance, not the folder itself. To remove a folder, use the delete folder action instead. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string | Yes | The scope of the metadata template. Must be one of: 'global' (for Box's built-in templates like 'properties'), 'enterprise' (for company-wide templates), or 'enterprise_{id}' format (e.g., 'enterprise_1351007304'). You can obtain the scope by listing metadata instances on the folder first. | | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `template_key` | string | Yes | The key/name of the metadata template to remove (e.g., 'properties', 'marketingCollateral'). This identifies which metadata instance to delete from the folder. You can obtain the template key by listing metadata instances on the folder first. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove metadata taxonomy **Slug:** `BOX_DELETE_METADATA_TAXONOMY` Permanently deletes a metadata taxonomy from the enterprise. This deletion is permanent and cannot be reverted. Once deleted, the taxonomy and all associated metadata will be removed from files and folders. Use with caution. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `namespace` | string | Yes | The namespace of the metadata taxonomy to delete. For enterprise taxonomies, this typically follows the format 'enterprise_{id}'. Example: 'enterprise_123456'. | | `taxonomy_key` | string | Yes | The key of the metadata taxonomy to delete. This is the unique identifier for the taxonomy within the namespace. Example: 'geography' or 'test_taxonomy_delete_12345'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove metadata taxonomy node **Slug:** `BOX_DELETE_METADATA_TAXONOMY_NODE` Permanently deletes a metadata taxonomy node from Box. Metadata taxonomies in Box allow you to organize and classify content using hierarchical structures. This action removes a specific node from a taxonomy. Important constraints: - Only nodes without any children can be deleted - This deletion is permanent and cannot be reverted - Requires admin or co-admin permissions - The user must have access to the metadata taxonomies feature Returns HTTP 204 No Content on successful deletion. Returns HTTP 400 Bad Request if the node has children or request is invalid. Returns HTTP 403 Forbidden if the user lacks necessary permissions. Returns HTTP 404 Not Found if the taxonomy or node does not exist. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `node_id` | string | Yes | The unique identifier of the metadata taxonomy node to delete. This is a UUID that identifies the specific node within the taxonomy tree (e.g., '14d3d433-c77f-49c5-b146-9dea370f6e32'). Only nodes without any children can be deleted. | | `namespace` | string | Yes | The namespace of the metadata taxonomy. This is typically the enterprise ID prefixed with 'enterprise_' (e.g., 'enterprise_123456'). You can get this from the taxonomy configuration or by listing metadata taxonomies. | | `taxonomy_key` | string | Yes | The key that identifies the metadata taxonomy. This is a unique identifier for the taxonomy within the namespace (e.g., 'geography', 'departments'). You can obtain this from the taxonomy configuration. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove metadata template **Slug:** `BOX_DELETE_METADATA_TEMPLATE` Permanently delete a metadata template and all its instances from files and folders. **WARNING**: This operation is destructive and cannot be undone. Once deleted: - The template definition is permanently removed - All metadata instances using this template on files/folders are also deleted - Any cascade policies using this template will stop working **Scope**: Use 'enterprise' for custom templates created within your organization. Global templates (scope='global') cannot be deleted. **Required Permission**: Requires 'manage enterprise properties' scope. Only enterprise admins can delete metadata templates. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string | Yes | The scope of the metadata template. Use 'enterprise' for custom templates created within your enterprise, or 'global' for Box's built-in templates. Note: You cannot delete global templates - only enterprise templates can be removed. | | `template_key` | string | Yes | The unique identifier (key) of the metadata template to delete. This is the templateKey value that was specified or auto-generated when the template was created (e.g., 'myCustomTemplate'). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete retention policy **Slug:** `BOX_DELETE_RETENTION_POLICY` Permanently deletes a retention policy from the Box enterprise. This action removes the specified retention policy. Once deleted, the policy cannot be recovered. Only modifiable retention policies can be deleted; non-modifiable policies used for regulatory compliance cannot be deleted. The authenticated user must have admin privileges and the application must have the 'manage_data_retention' or 'enterprise_content' scope enabled. Returns an empty response (HTTP 204) on successful deletion. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `retention_policy_id` | string | Yes | The unique identifier (ID) of the retention policy to permanently delete. This can be obtained from the response when creating a retention policy or by listing retention policies. Example: '12345678'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove retention policy assignment **Slug:** `BOX_DELETE_RETENTION_POLICY_ASSIGNMENT` Removes a retention policy assignment from content in Box. This action permanently removes the link between a retention policy and its assigned target (folder, enterprise, or metadata template). Once removed, the retention policy will no longer apply to the previously associated content. **Important restrictions:** - Only assignments for **modifiable** retention policies can be deleted. - Assignments for **non-modifiable** (regulatory) retention policies cannot be removed to ensure compliance with retention requirements. - Requires Box Governance license and admin permissions. **Required scopes:** manage_data_retention, enterprise_content **Returns:** HTTP 204 No Content on success (empty response body). #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `retention_policy_assignment_id` | string | Yes | The unique identifier of the retention policy assignment to remove. This ID can be obtained from the 'List retention policy assignments' action or from the response when assigning a retention policy. Example: '12345678'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove shared link from file **Slug:** `BOX_DELETE_SHARED_LINK_FROM_FILE` Removes a shared link from a file in Box. This action disables the shared link for the specified file, making it no longer accessible via the previously shared URL. The file itself is not deleted - only the shared link is removed. After successful execution, the shared_link field in the response will be null. This is an idempotent operation - calling it on a file that already has no shared link will succeed without error. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | Explicitly request the `shared_link` fields to be returned for this item. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove shared link from folder **Slug:** `BOX_DELETE_SHARED_LINK_FROM_FOLDER` Removes a shared link from a folder in Box. This action disables the shared link for the specified folder, making it no longer accessible via the previously shared URL. The folder itself is not deleted - only the shared link is removed. After successful execution, the shared_link field in the response will be null. This is an idempotent operation - calling it on a folder that already has no shared link will succeed without error. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | Explicitly request the `shared_link` fields to be returned for this item. | | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove shared link from web link **Slug:** `BOX_DELETE_SHARED_LINK_FROM_WEB_LINK` Removes a shared link from a web link in Box. This action disables the shared link for the specified web link, making it no longer accessible via the previously shared URL. The web link itself is not deleted - only the shared link is removed. After successful execution, the shared_link field in the response will be null. This is an idempotent operation - calling it on a web link that already has no shared link will succeed without error. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | Comma-separated list of fields to include in the response. Defaults to 'shared_link' to return the shared link status (which will be null after successful removal). | | `web_link_id` | string | Yes | The unique identifier of the web link. The ID can be found in the URL when viewing the web link in Box, e.g., for `https://app.box.com/web_link/123` the web_link_id is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete shield information barrier segment **Slug:** `BOX_DELETE_SHIELD_INFORMATION_BARRIER_SEGMENT` Permanently deletes a shield information barrier segment by its ID. Shield information barriers help prevent conflicts of interest by restricting collaboration between user segments within an organization. This action removes a specific segment from the barrier configuration. Requirements: - Box Shield add-on must be enabled for the enterprise - Admin privileges are required to delete segments - The segment must not have any active restrictions referencing it Returns HTTP 204 No Content on successful deletion. Returns HTTP 404 Not Found if the segment ID does not exist. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `shield_information_barrier_segment_id` | string | Yes | The unique identifier of the shield information barrier segment to delete. This ID is returned when creating a segment or can be retrieved by listing segments for a specific shield information barrier. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete shield information barrier segment member by id **Slug:** `BOX_DELETE_SHIELD_INFORMATION_BARRIER_SEGMENT_MEMBER_BY_ID` Removes a user from a shield information barrier segment by deleting their membership. Shield information barriers are used to prevent conflicts of interest by restricting communication and collaboration between specific groups of users within an enterprise. This action removes a user's membership from a specific barrier segment. Note: This feature requires Box Shield and is only available for enterprise accounts with the appropriate licensing. Returns 204 No Content on successful deletion. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `shield_information_barrier_segment_member_id` | string | Yes | The unique identifier of the shield information barrier segment member to delete. This ID can be obtained from the 'list_shield_information_barrier_segment_members' action or from the response when creating a segment member with 'create_shield_information_barrier_segment_member'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete Slack integration mapping **Slug:** `BOX_DELETE_SLACK_INTEGRATION_MAPPING` Deletes a Slack integration mapping that links a Box folder to a Slack channel. This endpoint removes an existing mapping between a Slack channel and a Box folder created through the Box for Slack integration. After deletion, any new files shared in the Slack channel will be stored in the default location rather than the previously mapped Box folder. **Requirements:** - Admin or Co-Admin role in the Box enterprise - Box for Slack must be installed in the relevant Slack workspace - Box as the Content Layer for Slack must be enabled **Note:** This action is irreversible. Once deleted, a new mapping must be created to restore the integration between the Slack channel and Box folder. For more information, see: https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `integration_mapping_id` | string | Yes | The unique identifier of the Slack integration mapping to delete. This ID can be obtained from the 'list_slack_integration_mappings' action. Example: '512521'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Unassign storage policy **Slug:** `BOX_DELETE_STORAGE_POLICY_ASSIGNMENT` Deletes a storage policy assignment, causing the assigned user to inherit the enterprise's default storage policy (Box Zone). Use this action when you want to reset a user's storage policy back to the enterprise default. This is useful when: - A user moves to a different region and should use the default zone - Cleaning up custom storage assignments - Reverting a user's data residency settings **Prerequisites**: Requires Box Zones feature to be enabled for the enterprise. **Rate Limit**: Only twice per user in a 24-hour period. **Response**: Returns 204 No Content on success (empty data object). #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `storage_policy_assignment_id` | string | Yes | The unique ID of the storage policy assignment to delete. Get this ID from 'list_storage_policy_assignments' or 'assign_storage_policy' response. Format is typically a numeric string like '12345678'. Note: This requires Box Zones feature to be enabled for the enterprise. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove task **Slug:** `BOX_DELETE_TASK` Permanently deletes a task from Box. Tasks are work assignments on files that can be assigned to collaborators for review or completion. Once deleted, the task and its assignments are permanently removed and cannot be recovered. Returns HTTP 204 (No Content) on successful deletion. Returns HTTP 404 if the task does not exist or has already been deleted. Use cases: - Remove completed tasks to clean up a file's task list - Cancel tasks that are no longer needed - Delete tasks created in error #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | The unique identifier (ID) of the task to permanently delete. You can get task IDs from BOX_CREATE_TASK, BOX_LIST_TASKS_ON_FILE, or BOX_GET_TASK actions. Example: '12345'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Unassign task **Slug:** `BOX_DELETE_TASK_ASSIGNMENT` Deletes a specific task assignment, removing the task from the assigned user. This action unassigns a user from a task without deleting the task itself. The task remains on the file and can be reassigned to other users. To delete the task entirely, use the 'remove_task' action instead. The authenticated user must have permission to modify task assignments on the file. Typically, this means being the user who created the assignment, the assigned user themselves, or having appropriate file access permissions. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_assignment_id` | string | Yes | The ID of the task assignment to delete. You can obtain this ID from the 'assign_task' action response, or by calling 'list_task_assignments' with a task_id. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete teams integration mapping **Slug:** `BOX_DELETE_TEAMS_INTEGRATION_MAPPING` Deletes a Microsoft Teams integration mapping that links a Box folder to a Teams channel. This endpoint removes an existing mapping between a Microsoft Teams channel or team and a Box folder created through the Box for Teams integration. After deletion, any new files shared in the Teams channel will be stored in the default location rather than the previously mapped Box folder. **Requirements:** - Admin or Co-Admin role in the Box enterprise - Box for Teams must be installed in the relevant Microsoft Teams workspace **Note:** This action is irreversible. Once deleted, a new mapping must be created to restore the integration between the Teams channel and Box folder. For more information, see: https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `integration_mapping_id` | string | Yes | The unique identifier of the Teams integration mapping to delete. This ID can be obtained from the 'list_teams_integration_mappings' action. Example: '12345678'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove upload session **Slug:** `BOX_DELETE_UPLOAD_SESSION` Abort and permanently remove a chunked upload session, discarding all uploaded data. This action is irreversible - once removed, all uploaded file parts are permanently deleted and the upload session cannot be recovered. Use this to cancel an in-progress chunked upload or clean up abandoned upload sessions. Returns HTTP 204 (No Content) on success. The upload_session_id can be obtained from the response of the 'Create upload session' or 'Get upload session' endpoints. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `upload_session_id` | string | Yes | The unique identifier of the upload session to abort and remove. This ID is returned when creating an upload session via the 'Create upload session' endpoint (e.g., '505380CEE884F26376849C43C4275690'). This operation is irreversible - all uploaded parts will be discarded. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete user **Slug:** `BOX_DELETE_USER` Permanently deletes a user from the enterprise. By default, deletion fails if the user still owns content, was recently active, or recently joined from a free account. Use the `force` parameter to bypass these restrictions and delete the user along with all their content. Returns an empty response (HTTP 204) on success. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `force` | boolean | No | Whether the user should be deleted even if they still own files, were recently active, or recently joined from a free account. When true, deletes the user and all their content. | | `notify` | boolean | No | Whether the user will receive email notification of the deletion. Defaults to true if not specified. | | `user_id` | string | Yes | The unique identifier (ID) of the user to delete. Example: '12345'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Delete user avatar **Slug:** `BOX_DELETE_USER_AVATAR` Deletes a user's custom avatar image from Box. This operation is irreversible. After deletion, the user will revert to the default Box avatar. If the user does not have a custom avatar set (only the default avatar), the operation will still succeed but indicate that no custom avatar was found. Note: This only removes custom uploaded avatars. Users always retain a default Box-generated avatar. Required scopes: root_readwrite or manage_managed_users #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `user_id` | string | Yes | The unique identifier (ID) of the Box user whose custom avatar should be deleted. This can be obtained from the user object or by listing enterprise users. Example: '12345678901'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove User Domain Exemption **Slug:** `BOX_DELETE_USER_DOMAIN_EXEMPTION` Removes a user's exemption from the enterprise's collaboration domain restrictions. After removal, the user will be subject to the allowed collaboration domain list configured for the enterprise and can no longer collaborate with users from domains outside of that list. PREREQUISITES: - The exemption must exist (obtain ID from 'List users exempt from collaboration domain restrictions' or when creating an exemption). - Requires enterprise admin privileges. - The enterprise must have collaboration domain restrictions enabled. COMMON ERRORS: - 204 No Content: Successful deletion (empty response body). - 403 Forbidden: Insufficient permissions or collaboration domain restrictions feature not enabled for the enterprise. - 404 Not Found: The specified exemption ID does not exist. NOTE: This is a destructive action. Once removed, the exemption cannot be recovered and the user will immediately be subject to domain restrictions. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `collaboration_whitelist_exempt_target_id` | string | Yes | The unique identifier of the user exemption record to remove. This ID is obtained from the 'List users exempt from collaboration domain restrictions' or 'Create user exemption from collaboration domain restrictions' actions. Example: '984923' | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove user from group **Slug:** `BOX_DELETE_USER_FROM_GROUP` Deletes a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `group_membership_id` | string | Yes | The unique identifier of the group membership to remove. This ID can be obtained from the BOX_ADD_USER_TO_GROUP action or by listing group members with BOX_LIST_MEMBERS_OF_GROUP. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove watermark from file **Slug:** `BOX_DELETE_WATERMARK_FROM_FILE` Removes the watermark from a file. This action deletes the watermark that was previously applied to the specified file. After removal, the file will no longer display watermark overlays when viewed or downloaded. Returns: - 204 No Content: Watermark successfully removed (empty response body) - 404 Not Found: File does not exist or has no watermark applied Note: This operation is idempotent. If the file doesn't have a watermark, the API will return a 404 error. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove watermark from folder **Slug:** `BOX_DELETE_WATERMARK_FROM_FOLDER` Removes the watermark from a folder. This action deletes the watermark applied to a specified folder. The folder must have a watermark applied to it, otherwise the API will return a 404 error. Only users with Owner, Co-owner, or Editor permissions on the folder can remove watermarks. This feature is available for Box Enterprise plans and above. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove webhook **Slug:** `BOX_DELETE_WEBHOOK` Permanently deletes a webhook from the Box account. Webhooks are used to receive notifications at a specified URL when events occur on Box content. Once deleted, the webhook will no longer send notifications for its configured triggers. This operation cannot be undone. To restore webhook functionality, you would need to create a new webhook with the same configuration. Returns an empty response (HTTP 204) on success. Returns 404 if the webhook ID does not exist or the user doesn't have access to it. Returns 403 if the application doesn't have the 'Manage Webhooks' permission scope. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `webhook_id` | string | Yes | The unique identifier of the webhook to delete. This ID is returned when creating a webhook or can be found by listing all webhooks. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Remove web link **Slug:** `BOX_DELETE_WEB_LINK` Deletes a web link. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `web_link_id` | string | Yes | The ID of the web link. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Permanently remove web link **Slug:** `BOX_DELETE_WEB_LINK_PERMANENTLY` Permanently deletes a web link that is in the trash. This action cannot be undone. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `web_link_id` | string | Yes | The unique identifier that represents a web link. The ID for any web link can be determined by visiting the web link in the web application and copying the ID from the URL. The web link must already be in the trash before it can be permanently deleted. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Download file **Slug:** `BOX_DOWNLOAD_FILE` Returns the contents of a file in binary format. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `version` | string | No | The file version ID to download. If not specified, the current (latest) version is downloaded. File versions can be obtained via the 'List all file versions' action. The version ID is the numeric identifier of the specific file version. | | `access_token` | string | No | An optional access token that can be used to pre-authenticate this request, which means that a download link can be shared with a browser or a third party service without them needing to know how to handle the authentication. When using this parameter, please make sure that the access token is sufficiently scoped down to only allow read access to that file and no other files or folders. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Download zip archive **Slug:** `BOX_DOWNLOAD_ZIP_ARCHIVE` Downloads a zip archive containing files and/or folders from Box. **Prerequisites**: You must first call 'BOX_CREATE_ZIP_DOWNLOAD' to create a zip download request. The response from that action contains a 'download_url' field, from which you should extract the 'zip_download_id'. **Important Notes**: - The download URL is only valid for a limited time (typically a few seconds after creation, or 12 hours once the download starts). - Once a download has started, it cannot be stopped and resumed. - If the download fails or times out, create a new zip download request. Returns the zip archive in binary format as a downloadable file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `zip_download_id` | string | Yes | The unique identifier for the zip archive to download. This ID is obtained from the 'download_url' field returned by the 'BOX_CREATE_ZIP_DOWNLOAD' action. Extract the ID from the URL path, e.g., from 'https://dl.boxcloud.com/2.0/zip_downloads//content', use the portion. | | `download_file_name` | string | No | The name to use for the downloaded zip file. Defaults to 'download.zip'. If you specified a 'download_file_name' when creating the zip download, you can use the same name here for consistency. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Extract metadata freeform **Slug:** `BOX_EXTRACT_METADATA_FREEFORM` Extract metadata from Box files using AI with freeform prompts. Use this action to extract custom metadata from files without needing a predefined metadata template. Box AI will analyze the file contents and extract information based on your prompt instructions. Features: - Freeform prompts: Specify exactly what metadata to extract using natural language - Flexible output: Response format adapts to your prompt (can be JSON, key-value pairs, etc.) - No template required: Unlike structured extraction, no metadata template setup needed Limitations: - Text documents: Up to 1MB per file - Maximum 25 files per request - Prompts: Maximum 10,000 characters Requires 'ai.readwrite' or 'manage_ai' scope in the access token. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `items` | array | Yes | List of files to extract metadata from. Provide 1-25 files. Each item requires 'id' (the file ID) and 'type' (must be 'file'). | | `prompt` | string | Yes | The prompt instructing Box AI what metadata to extract from the file(s). Maximum 10,000 characters. Can be formatted as plain text, XML, or JSON schema. Example: 'Extract the document title, author, creation date, and main topics.' | | `ai_agent` | object | No | Optional AI agent configuration. Can specify which LLM model to use for extraction. Provide either a reference to an existing agent (e.g., {'type': 'ai_agent_extract', 'id': '14031'}) or custom agent configuration. If not provided, Box will use the default AI agent. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Extract metadata structured **Slug:** `BOX_EXTRACT_METADATA_STRUCTURED` Extract structured metadata from files using Box AI. Uses Large Language Models (LLMs) to extract metadata as key-value pairs from files. Requires Box AI access (ai.readwrite scope). Supports two extraction approaches: 1. **Using fields**: Define custom fields with 'key', optional 'description', 'type', 'prompt', and 'options'. 2. **Using metadata_template**: Reference an existing Box metadata template by its template_key, type, and scope. You must use EITHER 'fields' OR 'metadata_template', but NOT both. Supports OCR for images (TIFF, PNG, JPEG) and scanned documents automatically. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `items` | array | Yes | The files to extract metadata from. Provide 1-25 file items. Each item must have 'id' (Box file ID) and 'type' set to 'file'. | | `fields` | array | No | Custom field definitions for extraction. Each field needs at least a 'key'. Optional: 'description', 'displayName', 'prompt', 'type', 'options'. Use EITHER 'fields' OR 'metadata_template' parameters, but NOT both. | | `metadata__template__type` | string ("metadata_template") | No | Must be set to 'metadata_template' when using a metadata template. Required if metadata_template_template_key is provided. | | `metadata__template__scope` | string | No | The scope of the metadata template. Use 'global' for Box-provided templates or 'enterprise_{enterprise_id}' for custom enterprise templates. Required if metadata_template_template_key is provided. | | `metadata__template__template__key` | string | No | The template_key of the metadata template to use for extraction. Required if using metadata_template approach instead of fields. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Find item for shared link **Slug:** `BOX_FIND_APP_ITEM_FOR_SHARED_LINK` Returns the file, folder, web link, or app item represented by a shared link. This endpoint allows you to retrieve information about any Box item (file, folder, web link, or app item) using its shared link URL. The shared link can originate from the current enterprise or another. While the action name references "app items", it works with all types of shared links in Box. The endpoint requires a valid shared link to be provided via the `boxapi` header or through the `shared_link` field. If the link is password-protected, provide the password via `shared_link_password`. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `boxapi` | string | No | Header value in the format `shared_link=&shared_link_password=`. If not provided, it will be constructed from `shared_link` and `shared_link_password` when available. Provide either this header or `shared_link`. | | `shared_link` | string | No | The shared link URL to the app item (e.g., `https://app.box.com/s/abcdef`). Used to authenticate the request via the `boxapi` header. Provide either this field or `boxapi`. | | `shared_link_password` | string | No | Password for the shared link, if the link is password-protected. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Find file for shared link **Slug:** `BOX_FIND_FILE_FOR_SHARED_LINK` Returns the file represented by a shared link. A shared file can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared file when only given a shared link. The `shared_link_permission_options` array field can be returned by requesting it in the `fields` query parameter. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `boxapi` | string | No | Header value in the format `shared_link=&shared_link_password=`. If not provided, it will be constructed from `shared_link` and `shared_link_password` when available. Provide either this header or `shared_link`. | | `fields` | string | No | A comma-separated list of field names to include in the response (e.g., 'name,size,shared_link'). Can be provided as a string or a list of strings. Use this to request fields that are not normally returned in the default response. To include shared link details, add 'shared_link' and/or 'shared_link_permission_options' to this list. When fields are specified, only the base fields (type, id, etag) plus the requested fields are returned. | | `shared_link` | string | No | The shared link URL to the item (e.g., `https://app.box.com/s/abcdef`). Used to authenticate the request via the `boxapi` header. Provide either this field or `boxapi`. | | `shared_link_password` | string | No | Password for the shared link, if the link is password-protected. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Find folder for shared link **Slug:** `BOX_FIND_FOLDER_FOR_SHARED_LINK` Return the folder represented by a shared link. A shared folder can be represented by a shared link, which can originate within the current enterprise or within another. This endpoint allows an application to retrieve information about a shared folder when only given a shared link. Conditional parameter requirements: - To retrieve the folder, you must supply a valid shared link via either the `shared_link` field (recommended) or the `boxapi` header string. If the shared link is password-protected, also provide `shared_link_password`. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `boxapi` | string | No | Explicit `boxapi` header value. If provided, it must be formatted as `shared_link=&shared_link_password=` (password segment optional). If not provided, this value is built from `shared_link` and `shared_link_password`. | | `fields` | array | No | A 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. Example: ['id', 'name', 'created_at', 'modified_at', 'shared_link'] | | `shared_link` | string | No | The shared link URL to the folder to retrieve. Provide either this field (preferred) or the `boxapi` header string. When provided, the action constructs the required `boxapi` header as `shared_link=&shared_link_password=` if a password is also supplied. | | `shared_link_password` | string | No | The password for the shared link, if the link is password-protected. Optional; only include when needed. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Find metadata template by instance id **Slug:** `BOX_FIND_METADATA_TEMPLATE_BY_INSTANCE_ID` Finds a metadata template by searching for the ID of an instance of the template. This action is useful when you have a metadata instance ID (the '$id' field from a metadata instance on a file or folder) and need to retrieve the full template definition including all field configurations. Common use case: After listing metadata instances on a file/folder, use this action to get the complete template schema to understand what fields are available. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of metadata templates to return per page. Defaults to API default if not specified. | | `marker` | string | No | Pagination marker from a previous response's 'next_marker' field. Used to retrieve the next page of results when paginating through metadata templates. | | `metadata_instance_id` | string | Yes | The unique UUID identifier of a metadata instance. This is the '$id' field returned when listing metadata instances on a file or folder (e.g., '17288cf2-6342-4f6a-bce1-bed1d8209524'). Use BOX_LIST_METADATA_INSTANCES_ON_FILE or BOX_LIST_METADATA_INSTANCES_ON_FOLDER to obtain this ID. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Force apply metadata cascade policy to folder **Slug:** `BOX_FORCE_APPLY_METADATA_CASCADE_POLICY_TO_FOLDER` Forces a metadata cascade policy to immediately apply the folder's metadata template to all existing child files and subfolders. This operation is asynchronous and returns immediately with HTTP 202 Accepted. Use cases: - After creating a new cascade policy to back-fill metadata on existing content - To retroactively apply metadata changes to all items in a folder hierarchy - When you need to enforce consistent metadata across all folder contents Important notes: - The cascade operation runs asynchronously in the background after the API returns - There is currently no API to check the status of this operation - Use the conflict_resolution parameter carefully to avoid unintended data overwrites - Only works with enterprise-scoped metadata templates (not global templates) - Newly added files/folders will automatically inherit metadata via the existing cascade policy Returns: HTTP 202 Accepted with an empty response body when the cascade operation is queued successfully. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `conflict_resolution` | string ("none" | "overwrite") | Yes | Specifies how to handle conflicts when a child file/folder already has a metadata instance of the same template applied: - 'none': Preserve existing metadata values on child items (no overwrite) - 'overwrite': Force-apply the folder's metadata values, replacing existing values on children This is required to prevent accidental data loss during the cascade operation. | | `metadata_cascade_policy_id` | string | Yes | The ID of the metadata cascade policy to force-apply. You can obtain this ID by creating a policy with BOX_CREATE_METADATA_CASCADE_POLICY or by listing policies with BOX_LIST_METADATA_CASCADE_POLICIES. The ID is a base64-encoded string containing the folder ID, enterprise ID, and template information. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Generate text **Slug:** `BOX_GENERATE_TEXT` Generate text using Box AI based on a prompt and file context. This action sends a request to Box AI's text generation endpoint, which uses Large Language Models (LLMs) to generate text based on your prompt and the content of a specified file. Use cases include: - Summarizing document content - Generating responses based on file content - Creating content drafts using file context - Answering questions about document content Note: Requires Box AI access (Business, Business Plus, Enterprise, or higher plans). Files up to 1MB of text content are supported. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `items` | array | Yes | A list containing exactly ONE file item to provide context for text generation. The file's text content (up to 1MB) will be used as context for the LLM. Each item must include 'id' (file ID) and 'type' (must be 'file'). | | `prompt` | string | Yes | The prompt or instruction for the LLM to respond to. Maximum length: 10,000 characters. Example: 'Summarize the key points of this document' or 'Generate a response email based on this content'. | | `ai_agent` | object | No | Optional configuration to specify which AI agent model to use for text generation. If not provided, the default Box AI agent will be used. | | `dialogue_history` | array | No | Optional conversation history to provide multi-turn context. Include previous prompts and their corresponding LLM answers to enable follow-up questions or continued conversations. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get AI Agent by ID **Slug:** `BOX_GET_AI_AGENT` Retrieves detailed information about a specific AI Agent by its unique identifier. **Use Cases:** - Get the current configuration and capabilities of an AI agent - Check the access state and allowed users/groups for an agent - Retrieve capability settings (ask, text_gen, extract) for an agent **Requirements:** - Box Enterprise Advanced account with Box AI Studio enabled - "Manage AI" scope must be enabled in the Box Developer Console **Example:** To get an agent with all capability details, use: agent_id="1234567890", fields=["ask", "text_gen", "extract"] #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | List of capability fields to include in the response. Specify which detailed capability configurations to return. Valid values: 'ask' (Q&A about documents), 'text_gen' (text generation), 'extract' (metadata extraction). Example: ['ask', 'text_gen'] returns both ask and text_gen capability details. If omitted, only basic agent metadata (id, name, type, access_state, etc.) is returned without capability configs. | | `agent_id` | string | Yes | The unique identifier of the AI Agent to retrieve. This is a numeric string ID (e.g., '12345678') obtained from creating an agent (BOX_CREATE_AI_AGENT) or listing agents (BOX_LIST_AI_AGENTS). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get ai agent default configuration **Slug:** `BOX_GET_AI_AGENT_DEFAULT_CONFIGURATION` Retrieve the default AI agent configuration for a specific mode. Returns the default AI agent settings used by Box AI features. The configuration includes model settings, token limits, LLM endpoint parameters, and tool configurations for text processing, image handling, and spreadsheet operations. Use this to understand or customize the AI agent behavior for ask, text generation, or metadata extraction operations. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mode` | string ("ask" | "extract" | "extract_structured" | "text_gen") | Yes | The AI operation mode to get the default configuration for. Options: 'ask' (Q&A about documents), 'text_gen' (generate text content), 'extract' (freeform metadata extraction), 'extract_structured' (structured metadata extraction). | | `model` | string | No | The AI model to return the default agent config for. Example models: 'openai__gpt_3_5_turbo', 'openai__gpt_4o_mini', 'google__gemini_1_5_flash_001'. If not specified, returns config for the default model. | | `language` | string | No | The ISO 639-1 language code to return the agent config for (e.g., 'en', 'ja', 'fr'). If the language is not supported, the default agent config is returned. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get allowed collaboration domain **Slug:** `BOX_GET_ALLOWED_COLLABORATION_DOMAIN` Retrieves details of a specific allowed collaboration domain entry within your enterprise. This endpoint returns information about a domain that has been whitelisted for collaboration, including the domain name, the direction of allowed collaborations (inbound, outbound, or both), and the enterprise that owns the entry. Use 'list_allowed_collaboration_domains' to get a list of all whitelist entry IDs, or use the ID returned when adding a new domain via 'add_domain_to_list_of_allowed_collaboration_domains'. Note: This endpoint requires enterprise admin privileges and the 'manage_enterprise_properties' scope. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `collaboration_whitelist_entry_id` | string | Yes | The unique identifier of the collaboration whitelist entry to retrieve. This ID can be obtained from the response of 'list_allowed_collaboration_domains' or 'add_domain_to_list_of_allowed_collaboration_domains' actions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get box sign request by id **Slug:** `BOX_GET_BOX_SIGN_REQUEST` Retrieves the details of a specific Box Sign request by its unique ID. Returns comprehensive information about the signature request including: - Request status (e.g., 'converting', 'created', 'sent', 'viewed', 'signed', 'declined', 'cancelled', 'expired', 'error_converting', 'error_sending') - Signers information with their email, role, decision status, and embed URLs - Source files included in the request - Signed document copies available for download (when completed) - Signing log reference - Request timestamps and sender information Note: Requires Box Sign to be enabled for the enterprise account. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sign_request_id` | string | Yes | The unique identifier (UUID) of the Box Sign request to retrieve. This ID can be obtained from the response when creating a sign request or by listing all sign requests. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Box Sign Template by ID **Slug:** `BOX_GET_BOX_SIGN_TEMPLATE` Retrieves details of a specific Box Sign template by its unique ID. Returns template configuration including name, email subject/message, signers, source files, destination folder, and various lock settings that control what can be modified when creating signature requests. Note: Templates can only be created and edited via the Box web application. This API is read-only for template data. Required scope: sign_requests.readwrite #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `template_id` | string | Yes | The unique identifier (ID) of the Box Sign template to retrieve. You can obtain template IDs by listing all templates using the List Box Sign Templates action. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get collaboration **Slug:** `BOX_GET_COLLABORATION` Retrieves details of a single collaboration by its ID. A collaboration represents shared access between a user/group and a file or folder in Box. This action returns information about who has access, what role they have, and which item the collaboration grants access to. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | A list of specific attributes to include in the response. Use this to request fields that are not normally returned in a standard response. When specified, only the mini representation fields plus the requested fields are returned. Example values: ['id', 'role', 'status', 'accessible_by', 'item', 'created_at', 'expires_at']. | | `collaboration_id` | string | Yes | The unique identifier of the collaboration to retrieve. This is a numeric string ID returned when creating or listing collaborations (e.g., '69886391395'). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get collection by id **Slug:** `BOX_GET_COLLECTION` Retrieves details of a specific collection by its unique identifier. Collections in Box are used to organize items (files and folders). Currently, Box only supports the 'favorites' collection, which contains items that the user has marked as favorites. Use 'list_all_collections' to discover available collection IDs. Returns the collection's id, type, name, and collection_type. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `collection_id` | string | Yes | The unique identifier of the collection to retrieve. Collection IDs can be obtained from the 'list_all_collections' action. Note: Box currently only supports the 'favorites' collection type. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get comment **Slug:** `BOX_GET_COMMENT` Retrieves the message and metadata for a specific comment, as well as information on the user who created the comment. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | 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. | | `comment_id` | string | Yes | The ID of the comment. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get current user **Slug:** `BOX_GET_CURRENT_USER` Retrieves information about the user who is currently authenticated. In the case of a client-side authenticated OAuth 2.0 application this will be the user who authorized the app. In the case of a JWT, server-side authenticated application this will be the service account that belongs to the application by default. Use the `As-User` header to change who this API call is made on behalf of. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | 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. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get device pin **Slug:** `BOX_GET_DEVICE_PIN` Retrieves information about an individual device pin in the enterprise. Device pins are created when users access Box from mobile or desktop devices that support device pinning. This endpoint returns details about a specific device pin including the device type and the user who owns it. The user must have admin privileges and the application needs the 'manage_enterprise_properties' scope to make this call. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `device_pinner_id` | string | Yes | The unique identifier of the device pin to retrieve. Device pin IDs can be obtained from the 'List enterprise device pins' endpoint. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Real-Time Server URL for Long-Polling Events **Slug:** `BOX_GET_EVENTS_LONG_POLL_ENDPOINT` Returns a list of real-time servers that can be used for long-polling user events. Long-polling allows applications to listen for events in real-time without repeatedly polling the /events endpoint. After calling this endpoint, make a GET request to the returned `url` to start listening for events. When events occur, the server responds with 'new_change' to signal that you should fetch events from GET /events. If no events occur within `retry_timeout` seconds, you'll receive 'reconnect' and should call this endpoint again to get a fresh URL. Note: Long-polling is only available for user events, not enterprise events. #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get file information **Slug:** `BOX_GET_FILE_INFORMATION` Retrieves the details about a file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | A comma-separated list of attributes to include in the response (e.g., 'name,size,created_at,modified_at'). This can be used to request fields that are not normally returned in a standard response. When specified, only the requested fields plus the base fields (id, type, etag) are returned. Common fields include: name, size, description, created_at, modified_at, path_collection, parent, sha1, shared_link, item_status, file_version. For metadata, use format: 'metadata.enterprise_12345.templateKey'. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get file request **Slug:** `BOX_GET_FILE_REQUEST` Retrieves detailed information about a file request in Box. File requests are forms that allow external users to upload files to a specific folder without needing a Box account. This action returns the file request's configuration including its title, description, status, associated folder, and the shareable URL. Note: File request IDs can only be obtained from the Box web application URL (e.g., https://*.app.box.com/filerequest/123). There is no API endpoint to list all file requests. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_request_id` | string | Yes | The unique identifier that represent a file request. The ID for any file request can be determined by visiting a file request builder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/filerequest/123` the `file_request_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get files under retention **Slug:** `BOX_GET_FILES_UNDER_RETENTION` Returns a paginated list of files under retention for a specific retention policy assignment. This endpoint is part of Box Governance and requires: - 'manage_retention_policies' scope enabled for the application - Global Content Manager (GCM) permissions, which must be enabled by Box support The response includes file metadata (id, name, sha1, etag) and file version information. Results are paginated using marker-based pagination. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Maximum value is 1000. | | `marker` | string | No | Cursor for marker-based pagination. Use the next_marker value from a previous response to retrieve the next page of results. | | `retention_policy_assignment_id` | string | Yes | The unique identifier (ID) of the retention policy assignment. Use the List retention policy assignments API to obtain valid assignment IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get file thumbnail **Slug:** `BOX_GET_FILE_THUMBNAIL` Retrieves a thumbnail, or smaller image representation, of a file. Sizes of `32x32`,`64x64`, `128x128`, and `256x256` can be returned in the `.png` format and sizes of `32x32`, `160x160`, and `320x320` can be returned in the `.jpg` format. Thumbnails can be generated for the image and video file formats listed [found on our community site][1]. [1]: https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327 #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `extension` | string ("jpg" | "png") | Yes | The file format for the thumbnail. 'png' supports sizes 32x32, 64x64, 128x128, and 256x256. 'jpg' supports sizes 32x32, 160x160, and 320x320. | | `max_width` | integer | No | The maximum width of the thumbnail in pixels (range: 32-320). Box will return a thumbnail no wider than this. | | `min_width` | integer | No | The minimum width of the thumbnail in pixels (range: 32-320). Box will return a thumbnail at least this wide. | | `max_height` | integer | No | The maximum height of the thumbnail in pixels (range: 32-320). Box will return a thumbnail no taller than this. | | `min_height` | integer | No | The minimum height of the thumbnail in pixels (range: 32-320). Box will return a thumbnail at least this tall. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get file version **Slug:** `BOX_GET_FILE_VERSION` Retrieve detailed information about a specific version of a file. This action returns metadata about a file version including its SHA1 hash, size, creation date, and who modified it. Versions are only tracked for Box users with premium accounts. Use BOX_LIST_ALL_FILE_VERSIONS to get a list of all available versions for a file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | 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. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `file_version_id` | string | Yes | The ID of the file version to retrieve. Version IDs can be obtained from the BOX_LIST_ALL_FILE_VERSIONS action or from the file_version.id field returned when uploading or updating files. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get file version legal hold **Slug:** `BOX_GET_FILE_VERSION_LEGAL_HOLD` Retrieves detailed information about a specific file version legal hold by its ID. A file version legal hold represents the preservation of a specific file version due to legal hold policies. This action returns the hold details including which file and file version are held, and which legal hold policy assignments created the hold. Use this action when you need to inspect the legal hold status and details for a specific file version legal hold record. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_version_legal_hold_id` | string | Yes | The ID of the file version legal hold. This can be obtained from the BOX_LIST_FILE_VERSION_LEGAL_HOLDS action or from legal hold policy assignment file versions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get file versions under retention **Slug:** `BOX_GET_FILE_VERSIONS_UNDER_RETENTION` Returns a list of file versions under retention for a specified retention policy assignment. A retention policy assignment links a retention policy to content (enterprise, folder, or metadata template). This endpoint retrieves all file versions that are currently being retained under the specified assignment. Use cases: - Audit which file versions are being retained under a specific policy assignment - Monitor retention compliance for specific folders or metadata templates - Track file versions before their disposition date Prerequisites: - Requires a valid retention_policy_assignment_id (obtain from 'List retention policy assignments' endpoint) - Requires the 'manage_data_retention' scope enabled for the application Note: Retention policies are an enterprise feature and require Box Governance or similar Box product. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Maximum value is 1000. | | `marker` | string | No | Defines the position marker at which to begin returning results for pagination. Use the 'next_marker' value from a previous response to fetch the next page of results. | | `retention_policy_assignment_id` | string | Yes | The unique identifier of the retention policy assignment. Can be obtained from the 'List retention policy assignments' endpoint using a retention_policy_id. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get folder information **Slug:** `BOX_GET_FOLDER` Retrieves details for a folder, including the first 100 entries in the folder. Passing `sort`, `direction`, `offset`, and `limit` parameters in query allows you to manage the list of returned [folder items](r://folder--full#param-item-collection). To fetch more items within the folder, use the [Get items in a folder](e://get-folders-id-items) endpoint. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sort` | string ("date" | "id" | "name" | "size") | No | Defines the **second** attribute by which items are sorted. The folder type affects the way the items are sorted: * **Standard folder**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. * **Root folder**: This parameter is not supported for marker-based pagination on the root folder (the folder with an `id` of `0`). * **Shared folder with parent path to the associated folder visible to the collaborator**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. | | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | 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. Additionally this field can be used to query any metadata applied to the file by specifying the `metadata` field as well as the scope and key of the template to retrieve, for example `?fields=metadata.enterprise_12345.contractTemplate`. | | `offset` | integer | No | The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | | `direction` | string ("ASC" | "DESC") | No | The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. | | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get group **Slug:** `BOX_GET_GROUP` Retrieves information about a group. Only members of this group or users with admin-level permissions will be able to use this API. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | A comma-separated list of attributes to include in the response. Available fields: id, type, name, group_type, created_at, modified_at, provenance, external_sync_identifier, description, invitability_level, member_viewability_level, permissions. Example: 'name,description,created_at'. Note: When specified, only the requested fields plus base fields (type, id) are returned. | | `group_id` | string | Yes | The unique identifier (ID) of the group to retrieve. Example: '12345678'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get group membership **Slug:** `BOX_GET_GROUP_MEMBERSHIP` Retrieves a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | 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. | | `group_membership_id` | string | Yes | The ID of the group membership. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get legal hold policy **Slug:** `BOX_GET_LEGAL_HOLD_POLICY` Retrieve detailed information about a specific legal hold policy by its ID. Legal hold policies preserve content for litigation or compliance purposes by preventing deletion or modification. This action returns the policy's name, description, status (active/applying/releasing/released), assignment counts by type (user/folder/file/ file_version/ownership/interactions), creator info, and timestamps. Prerequisites: - Box Governance add-on must be enabled for the enterprise - Requires 'manage_legal_holds' or 'enterprise_content' OAuth scope - Admin or co-admin role required To enable Legal Hold: https://www.box.com/business/governance-and-compliance #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `legal_hold_policy_id` | string | Yes | The unique identifier of the legal hold policy. Can be obtained from BOX_CREATE_LEGAL_HOLD_POLICY or BOX_LIST_ALL_LEGAL_HOLD_POLICIES actions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get legal hold policy assignment **Slug:** `BOX_GET_LEGAL_HOLD_POLICY_ASSIGNMENT` Retrieves detailed information about a specific legal hold policy assignment by its ID. Legal hold policy assignments link a legal hold policy to specific items (files, folders, file versions, users, ownership-based content, or user interactions). When a policy is assigned, it places a legal hold on the relevant file versions, preventing them from being deleted or modified until the hold is released. The response includes the assignment ID, the associated legal hold policy, the assigned item details, the user who created the assignment, creation timestamp, and deletion timestamp (if applicable). Prerequisites: - Requires Box Governance add-on (Box Enterprise Plus or higher) - Requires 'manage_legal_holds' or 'enterprise_content' OAuth scope - Admin or co-admin role required Use cases: - Verify legal hold coverage on specific items - Audit legal hold assignments for compliance - Check assignment status and metadata #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `legal_hold_policy_assignment_id` | string | Yes | The unique identifier (ID) of the legal hold policy assignment to retrieve. This ID is returned when creating an assignment via 'assign_legal_hold_policy' or can be obtained by listing assignments with 'list_legal_hold_policy_assignments'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get metadata cascade policy **Slug:** `BOX_GET_METADATA_CASCADE_POLICY` Retrieve a specific metadata cascade policy assigned to a folder. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `metadata_cascade_policy_id` | string | Yes | The ID of the metadata cascade policy. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get metadata instance on file **Slug:** `BOX_GET_METADATA_INSTANCE_ON_FILE` Retrieves a specific metadata template instance that has been applied to a file. This action returns the metadata key-value pairs for a particular template on a file. Use BOX_LIST_METADATA_INSTANCES_ON_FILE first to discover which templates are applied to a file if you don't know the scope and template_key. Common error codes: - 404 (instance_not_found): The metadata template has not been applied to this file. - 404 (not_found): The file was not found or the user does not have access. - 403 (forbidden): The user does not have permission to view this metadata. Example usage: - Get global properties: scope='global', template_key='properties' - Get enterprise classification: scope='enterprise', template_key='classification' - Get custom template: scope='enterprise', template_key='yourCustomTemplate' #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string ("enterprise" | "global") | Yes | The scope of the metadata template. Use 'global' for Box's built-in templates (e.g., 'properties', 'boxSkillsCards') or 'enterprise' for custom templates created by your organization. The API automatically resolves 'enterprise' to your enterprise ID (e.g., 'enterprise_12345'). | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `template_key` | string | Yes | The key of the metadata template to retrieve. Common templates include 'properties' (global template for arbitrary key-value pairs), 'classification' (enterprise security classification), and custom enterprise templates. Use BOX_LIST_METADATA_INSTANCES_ON_FILE to discover which templates are applied to a file, or BOX_LIST_ALL_METADATA_TEMPLATES_FOR_ENTERPRISE to see available enterprise templates. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get metadata instance on folder **Slug:** `BOX_GET_METADATA_INSTANCE_ON_FOLDER` Retrieves the instance of a metadata template that has been applied to a folder. This can not be used on the root folder with ID `0`. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string | Yes | The scope of the metadata template. Use 'global' for global templates or 'enterprise' for enterprise templates (or 'enterprise_NNNN' for specific enterprise ID). | | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `template_key` | string | Yes | The key/name of the metadata template. For global templates, use 'properties'. For enterprise templates, use the template key defined when the template was created. Example: 'properties' for global.properties template. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get metadata taxonomies for namespace **Slug:** `BOX_GET_METADATA_TAXONOMIES_FOR_NAMESPACE` Retrieves all metadata taxonomies within a specific namespace. Use this when you need to list all taxonomy templates available in an enterprise namespace. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | | `namespace` | string | Yes | The namespace of the metadata taxonomy. This is typically in the format 'enterprise_{enterprise_id}' where enterprise_id is your enterprise ID number. For example, 'enterprise_123456'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get metadata taxonomy by taxonomy key **Slug:** `BOX_GET_METADATA_TAXONOMY_BY_TAXONOMY_KEY` Retrieves a metadata taxonomy by its namespace and taxonomy key. Use when you need to fetch detailed information about a specific taxonomy structure. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `namespace` | string | Yes | The namespace of the metadata taxonomy. This is typically in the format 'enterprise_{enterprise_id}' where enterprise_id is your organization's unique identifier. For example: 'enterprise_123456'. | | `taxonomy_key` | string | Yes | The key of the metadata taxonomy. This is a unique identifier for the specific taxonomy within the namespace. For example: 'geography' or 'departments'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get metadata taxonomy node by ID **Slug:** `BOX_GET_METADATA_TAXONOMY_NODE_BY_ID` Retrieves a specific node from a metadata taxonomy by its identifier. Use when you need to get details about a particular taxonomy node including its display name, level, and ancestor information. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `node_id` | string | Yes | The unique identifier of the metadata taxonomy node to retrieve. This is a UUID that identifies a specific node within the taxonomy hierarchy. | | `namespace` | string | Yes | The namespace of the metadata taxonomy. This typically follows the format 'enterprise_{enterprise_id}' where enterprise_id is your Box enterprise ID. | | `taxonomy_key` | string | Yes | The key of the metadata taxonomy. This is the unique identifier for the specific taxonomy within the namespace. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get metadata template by id **Slug:** `BOX_GET_METADATA_TEMPLATE_BY_ID` Retrieves a metadata template by its ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `template_id` | string | Yes | The UUID of the metadata template (e.g., 'f7a9891f-9b0c-4b2a-bc9a-123456789012'). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get metadata template by name **Slug:** `BOX_GET_METADATA_TEMPLATE_BY_NAME` Retrieves a metadata template by its `scope` and `templateKey` values. To find the `scope` and `templateKey` for a template, list all templates for an enterprise or globally, or list all templates applied to a file or folder. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string | Yes | The scope of the metadata template. Must be 'enterprise' for custom templates created by your organization, or 'global' for Box-provided templates. | | `template_key` | string | Yes | The unique identifier (templateKey) of the metadata template. For example: 'FormsTemplatesInfo', 'MalwareDeepScan', or custom template keys for enterprise templates. You can find template keys by listing all templates for the enterprise or globally. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get retention on file **Slug:** `BOX_GET_RETENTION_ON_FILE` Returns information about a file version retention. **Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_version_retention_id` | string | Yes | The unique identifier of the file version retention record. Note: This API is deprecated. Use the 'get file versions under retention' endpoint (get-retention-policy-assignments-id-file-versions-under-retention) instead for current implementations. Example: '3424234' | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get retention policy **Slug:** `BOX_GET_RETENTION_POLICY` Retrieves a retention policy by its unique ID. Retention policies define how long content is retained before being automatically deleted or having the retention removed. This is an enterprise-level feature that requires the 'manage_data_retention' OAuth scope to be enabled. Returns details including policy name, retention length, disposition action, status, and assignment counts. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | Comma-separated list of attributes to include in the response. Example: 'id,type,policy_name,retention_length'. Available fields: id, type, policy_name, retention_length, disposition_action, description, policy_type, retention_type, status, created_by, created_at, modified_at, can_owner_extend_retention, are_owners_notified, custom_notification_recipients, assignment_counts. If specified, only these fields plus mini representation fields are returned. | | `retention_policy_id` | string | Yes | The unique identifier (ID) of the retention policy to retrieve. Example: '982312'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get retention policy assignment **Slug:** `BOX_GET_RETENTION_POLICY_ASSIGNMENT` Retrieves a retention policy assignment by its unique ID. A retention policy assignment represents a link between a retention policy and its target (a folder, the enterprise, or a metadata template). This action returns details about where and how the retention policy is applied. Requires Box Governance license and scopes: manage_data_retention, enterprise_content. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | A comma-separated list of attributes to include in the response. If not specified, standard fields are returned. Available fields include: 'id', 'type', 'retention_policy', 'assigned_to', 'filter_fields', 'assigned_by', 'assigned_at', 'start_date_field'. When specified, only requested fields and mini representation fields are returned. | | `retention_policy_assignment_id` | string | Yes | The unique identifier (ID) of the retention policy assignment to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get shared link for file **Slug:** `BOX_GET_SHARED_LINK_FOR_FILE` Retrieves the shared link information for a file. This action fetches details about an existing shared link, including the URL, access level, permissions, and usage statistics. If the file does not have a shared link, the shared_link field in the response will be null. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | A comma-separated list of attributes to include in the response. Use 'shared_link' to retrieve the shared link information. Defaults to 'shared_link'. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get shared link for folder **Slug:** `BOX_GET_SHARED_LINK_FOR_FOLDER` Retrieves shared link information for a folder. This action fetches the shared link details for a specified folder, including the public URL, access level, permissions, and usage statistics. If the folder does not have a shared link, the 'shared_link' field in the response will be null. Use the 'fields' parameter to request additional folder information beyond just the shared link. This is useful for getting context about the folder (name, path, owner) in the same request. Note: This action only retrieves existing shared link information. To create a shared link, use the 'add_shared_link_to_folder' action. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | Comma-separated list of fields to include in the response. Defaults to 'shared_link' which returns only the shared link information along with basic folder identifiers (id, type, etag). Common additional fields include: 'name' (folder name), 'created_at' (creation timestamp), 'modified_at' (last modified timestamp), 'path_collection' (folder path), 'owned_by' (owner info), 'size' (folder size). Example: 'shared_link,name,created_at,owned_by'. | | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get shared items web links **Slug:** `BOX_GET_SHARED_WEB_LINK` Tool to retrieve web link information for a shared link. Use when you have a Box shared link URL and need to get details about the web link object it points to. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `boxapi` | string | Yes | A header containing the shared link and optional password for the shared link. The format for this header is as follows: `shared_link=[link]&shared_link_password=[password]`. Example: 'shared_link=https://app.box.com/s/abc123' | | `fields` | array | No | 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. | | `if_none_match` | string | No | Ensures an item is only returned if it has changed. Pass in the item's last observed `etag` value into this header and the endpoint will fail with a `304 Not Modified` if the item has not changed since. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get shield information barrier with specified id **Slug:** `BOX_GET_SHIELD_INFORMATION_BARRIER_BY_ID` Retrieves a shield information barrier by its unique ID. Shield information barriers are used to separate individuals/groups within the same enterprise and prevent confidential information from passing between them. Note: This feature requires Box Shield enterprise licensing. Returns 404 if the barrier ID doesn't exist or if Shield is not enabled for the enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `shield_information_barrier_id` | string | Yes | The unique identifier of the shield information barrier to retrieve. This ID is returned when creating or listing shield information barriers. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get shield information barrier report by id **Slug:** `BOX_GET_SHIELD_INFORMATION_BARRIER_REPORT_BY_ID` Retrieves a shield information barrier report by its ID. Shield information barrier reports provide information about users and groups that are affected by shield information barriers in the enterprise. Reports include details about which users are in which segments and any policy violations. Note: This endpoint requires Box Shield, an enterprise add-on feature. The report must exist and belong to a barrier in your enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `shield_information_barrier_report_id` | string | Yes | The unique identifier of the shield information barrier report to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get shield information barrier segment with specified id **Slug:** `BOX_GET_SHIELD_INFORMATION_BARRIER_SEGMENT_BY_ID` Retrieves a shield information barrier segment by its unique identifier. Shield information barriers are used to prevent conflicts of interest by restricting communication between specific groups of users. Segments define groups of users within a barrier. Note: This feature requires Box Shield, which is an enterprise-level add-on. The API will return 404 if Shield is not enabled for the enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `shield_information_barrier_segment_id` | string | Yes | The unique identifier of the shield information barrier segment to retrieve. This ID is returned when creating or listing segments. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get shield information barrier segment member by id **Slug:** `BOX_GET_SHIELD_INFORMATION_BARRIER_SEGMENT_MEMBER_BY_ID` Retrieves a shield information barrier segment member by its unique ID. Shield Information Barriers enforce compliance by restricting collaboration between departments (e.g., Investment Banking vs Research in financial institutions). Returns details about a user's segment assignment including when added, by whom, and which barrier/segment. Prerequisites: Box Shield license, valid member ID from create/list operations. Returns 200 on success, 404 if not found or feature disabled. Related: create_shield_information_barrier_segment_member, list_shield_information_barrier_segment_members #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `shield_information_barrier_segment_member_id` | string | Yes | **Required**. The unique identifier of the shield information barrier segment member to retrieve. Obtain this ID from create_shield_information_barrier_segment_member or list_shield_information_barrier_segment_members actions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get shield information barrier segment restriction by id **Slug:** `BOX_GET_SHIELD_INFORMATION_BARRIER_SEGMENT_RESTRICTION_BY_ID` Retrieves a shield information barrier segment restriction by its unique ID. Shield information barrier segment restrictions define which segments cannot communicate or collaborate with each other. This action fetches the details of a specific restriction including the requesting segment, restricted segment, and the parent barrier information. Note: This feature requires Box Shield subscription and enterprise-level access. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `shield_information_barrier_segment_restriction_id` | string | Yes | The unique identifier of the shield information barrier segment restriction to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get storage policy **Slug:** `BOX_GET_STORAGE_POLICY` Fetches a specific storage policy by its ID. Storage policies define the geographic location where content is stored (data residency). This is an enterprise feature that requires Box Zones or similar subscription. Use this action to get details about a storage policy, including its name and the geographic region(s) it covers. To find available storage policy IDs, first use the 'list_storage_policies' action. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `storage_policy_id` | string | Yes | The unique numeric ID of the storage policy to retrieve. Storage policy IDs can be obtained using the 'list_storage_policies' action. Example: '12345' or '1434325'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get storage policy assignment **Slug:** `BOX_GET_STORAGE_POLICY_ASSIGNMENT` Retrieves information about a specific storage policy assignment. Storage policies control where data is physically stored (data residency). This action requires the Box Zones add-on or equivalent enterprise feature. Use 'list_storage_policy_assignments' to find assignment IDs for users or the enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `storage_policy_assignment_id` | string | Yes | The ID of the storage policy assignment to retrieve (e.g., '932483' or 'ZW50ZXJwcmlzZV8xMjM0NTY3ODkw'). Obtain this from the 'list_storage_policy_assignments' action or from a previous 'assign_storage_policy' response. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get task **Slug:** `BOX_GET_TASK` Retrieves detailed information about a specific task in Box. A task is a to-do item that can be assigned to users for a specific file. Tasks can be of type 'review' (approval workflow) or 'complete' (general task). Use this action to get task details including the associated file, assignees, due date, message, and completion status. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | The unique identifier of the task to retrieve. Task IDs can be obtained from BOX_LIST_TASKS_ON_FILE or BOX_CREATE_TASK responses. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get task assignment **Slug:** `BOX_GET_TASK_ASSIGNMENT` Retrieves detailed information about a specific task assignment in Box. A task assignment represents a task that has been assigned to a specific user. This endpoint returns information including: - The file associated with the task - The user the task is assigned to - The user who created the assignment - The assignment status (incomplete, completed, approved, or rejected) - Timestamps for assignment, completion, and reminders #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_assignment_id` | string | Yes | The unique identifier of the task assignment to retrieve. This ID can be obtained from BOX_ASSIGN_TASK or BOX_LIST_TASK_ASSIGNMENTS actions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get terms of service **Slug:** `BOX_GET_TERMS_OF_SERVICE` Retrieves a specific terms of service by its unique identifier. Returns the full terms of service object including: - Status (enabled/disabled) - Terms text content - Type (managed users or external collaborators) - Associated enterprise information - Creation and modification timestamps Note: This endpoint requires the Terms of Service feature to be enabled for the enterprise. Admin permissions may be required to access this data. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `terms_of_service_id` | string | Yes | The unique identifier of the terms of service to retrieve. Use 'list_terms_of_services' action to find available IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get trashed file **Slug:** `BOX_GET_TRASHED_FILE` Retrieves a file that has been moved to the trash. Please note that only if the file itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. To list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](e://get-folders-trash-items/) API. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | A comma-separated list of specific attributes to include in the response. Common fields: 'id', 'name', 'size', 'trashed_at', 'purged_at', 'created_by', 'modified_by', 'owned_by', 'parent', 'path_collection'. When specified, only the requested fields (plus mini representation fields like 'type', 'id', 'etag') are returned. Can be provided as a string (comma-separated) or as a list of strings. | | `file_id` | string | Yes | The unique identifier of a trashed file to retrieve. The file must have been directly deleted (moved to trash), not deleted as part of a parent folder deletion. You can find the file ID from the URL in the Box web app (e.g., for `https://*.app.box.com/files/123` the file_id is `123`) or by listing trashed items. Returns 404 if the file is not found in the trash. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get trashed folder **Slug:** `BOX_GET_TRASHED_FOLDER` Retrieves a folder that has been moved to the trash. Please note that only if the folder itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the [`GET /folders/:id/trash`](e://get_folders_id_trash) API. To list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](e://get-folders-trash-items/) API. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | 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. | | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get trashed web link **Slug:** `BOX_GET_TRASHED_WEB_LINK` Retrieves a web link that has been moved to the trash. Returns detailed information about a trashed web link including its original URL, name, description, creator, when it was trashed, and when it will be permanently purged. The web link must exist in the trash (not permanently deleted) for this action to succeed. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | A list of attributes to include in the response. Available fields include: id, type, name, url, description, created_at, modified_at, trashed_at, purged_at, item_status, created_by, modified_by, owned_by, parent, path_collection, shared_link, sequence_id, etag. If not specified, returns all standard fields. Note that specifying this parameter returns only mini representation fields plus the requested fields. | | `web_link_id` | string | Yes | The unique identifier of the trashed web link to retrieve. You can find trashed web link IDs by listing trashed items. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get upload session **Slug:** `BOX_GET_UPLOAD_SESSION` Retrieves detailed information about an existing chunked upload session. Returns the session status including: - Total number of parts expected for the file upload - Size of each part in bytes - Number of parts already processed/uploaded - Session expiration timestamp - Available endpoints for uploading parts, committing, aborting, and checking status Use this action to monitor upload progress or retrieve session endpoints needed to continue a chunked file upload. The upload_session_id is obtained from the 'Create upload session' action. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `upload_session_id` | string | Yes | The unique identifier (ID) of the chunked upload session. This ID is returned by the 'Create upload session' action when initiating a new chunked file upload. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get user **Slug:** `BOX_GET_USER` Retrieves information about a user in the enterprise. The application and the authenticated user need to have the permission to look up users in the entire enterprise. This endpoint also returns a limited set of information for external users who are collaborated on content owned by the enterprise for authenticated users with the right scopes. In this case, disallowed fields will return null instead. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | 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. Can be provided as a string (comma-separated) or as a list of strings. | | `user_id` | string | Yes | The ID of the user. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get user avatar **Slug:** `BOX_GET_USER_AVATAR` Retrieves the avatar image of a Box user. Returns a FileDownloadable object containing the avatar image. Returns 404 if the user has no avatar set. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `user_id` | string | Yes | The unique identifier of the Box user whose avatar to retrieve (e.g., '12345678'). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get user exempt from collaboration domain restrictions **Slug:** `BOX_GET_USER_EXEMPT_FROM_COLLABORATION_DOMAIN_RESTRICTIONS` Retrieves details of a specific user exemption from collaboration domain restrictions. This endpoint returns information about a user who has been granted an exemption from the enterprise's collaboration domain allowlist, allowing them to collaborate with external parties from any domain. PREREQUISITES: - The enterprise MUST have collaboration domain restrictions enabled. - The authenticated user must have admin privileges. - The exemption ID must exist (obtained from creating an exemption or listing exempt users). COMMON ERRORS: - 403 Forbidden: Enterprise doesn't have collaboration domain restrictions enabled, or the authenticated user lacks admin permissions. - 404 Not Found: The specified exemption ID does not exist. USE CASE: Use this to verify a specific user's exemption status or retrieve exemption metadata after creating or discovering an exemption ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `collaboration_whitelist_exempt_target_id` | string | Yes | The unique identifier of the collaboration domain exemption record. This ID is returned when creating a user exemption or when listing all exempt users. Example: '984923'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get user invite status **Slug:** `BOX_GET_USER_INVITE_STATUS` Returns the status of a user invite. This endpoint retrieves detailed information about a specific invite, including: - The invited user's details (email, name, ID) - The enterprise they were invited to - The user who created the invite - The invite status (e.g., 'pending', 'accepted') - Creation and modification timestamps Note: The invite_id must be obtained from creating an invite using the BOX_CREATE_USER_INVITE action. This endpoint requires the 'manage_enterprise' scope. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | 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. Can be provided as a string (comma-separated) or as a list of strings. Example: 'id,type,status' or ['id', 'type', 'status'] | | `invite_id` | string | Yes | The unique identifier of the invite to retrieve. This ID is returned when creating an invite using the BOX_CREATE_USER_INVITE action. Example: '213723' | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get watermark on file **Slug:** `BOX_GET_WATERMARK_ON_FILE` Retrieve the watermark for a file. Returns the watermark information (created_at and modified_at timestamps) for a file that has a watermark applied. If the file does not have a watermark, a 404 Not Found error is returned. Prerequisites: - The file must exist in Box - A watermark must have been applied to the file using BOX_APPLY_WATERMARK_TO_FILE Use BOX_APPLY_WATERMARK_TO_FILE to apply a watermark to a file first if needed. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get watermark for folder **Slug:** `BOX_GET_WATERMARK_ON_FOLDER` Retrieve the watermark for a folder. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get webhook **Slug:** `BOX_GET_WEBHOOK` Retrieves detailed information about a specific webhook by its ID. Use this action to get the configuration of an existing webhook, including the target item being monitored (file or folder), the notification URL, the event triggers, and who created the webhook. Note: This action requires the 'Manage Webhooks' scope to be enabled for the application. The webhook must exist and be accessible to the authenticated user. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `webhook_id` | string | Yes | The unique identifier of the webhook to retrieve. This ID is returned when creating a webhook or can be obtained from the list webhooks endpoint. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get web link **Slug:** `BOX_GET_WEB_LINK` Retrieve detailed information about a web link (bookmark) in Box. Returns the full web link object including its URL, name, description, parent folder, path collection, creation and modification timestamps, and ownership details. Web links are bookmarks to external URLs stored in Box folders. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `web_link_id` | string | Yes | The unique identifier (numeric ID) of the web link to retrieve. You can obtain this ID from the response when creating a web link or from listing folder items. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get zip download status **Slug:** `BOX_GET_ZIP_DOWNLOAD_STATUS` Get the download status of a zip archive, including progress, skipped items, and current state. **Prerequisites:** Call 'BOX_CREATE_ZIP_DOWNLOAD' first to get a zip_download_id, then initiate the download via 'BOX_DOWNLOAD_ZIP_ARCHIVE'. The status endpoint is only accessible after the download starts and remains valid for 12 hours. Skipped files/folders indicate permission issues. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `zip_download_id` | string | Yes | The unique identifier for the zip archive. This ID is extracted from the 'status_url' field returned by 'BOX_CREATE_ZIP_DOWNLOAD'. For example, from 'https://api.box.com/2.0/zip_downloads/{ID}/status', use the {ID} portion. NOTE: The status endpoint is only accessible after the download has been initiated and remains valid for 12 hours. The zip download expires quickly (typically within seconds) if not started. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List ai agents **Slug:** `BOX_LIST_AI_AGENTS` Lists AI agents based on the provided parameters. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mode` | array | No | The mode to filter the agent config to return. Possible values are: `ask`, `text_gen`, and `extract`. | | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | The fields to return in the response. | | `marker` | string | No | Defines the position marker at which to begin returning results. | | `agent_state` | array | No | The state of the agents to return. Possible values are: `enabled`, `disabled` and `enabled_for_selected_users`. | | `include_box_default` | boolean | No | Whether to include the Box default agents in the response. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List all classifications **Slug:** `BOX_LIST_ALL_CLASSIFICATIONS` Retrieves the classification metadata template and lists all the classifications available to this enterprise. This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`. Note: Returns a 404 if no classifications have been added to the enterprise yet. In this case, the action returns an empty classifications list. #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List all collections **Slug:** `BOX_LIST_ALL_COLLECTIONS` Retrieves all collections for a given user. Currently, only the `favorites` collection is supported. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | 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. | | `offset` | integer | No | The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List all file versions **Slug:** `BOX_LIST_ALL_FILE_VERSIONS` Retrieve a list of the past versions for a file. Versions are only tracked by Box users with premium accounts. To fetch the ID of the current version of a file, use the `GET /file/:id` API. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Maximum allowed value is 1000. | | `fields` | array | No | 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. | | `offset` | integer | No | The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List all global metadata templates **Slug:** `BOX_LIST_ALL_GLOBAL_METADATA_TEMPLATES` Used to retrieve all generic, global metadata templates available to all enterprises using Box. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List allowed collaboration domains **Slug:** `BOX_LIST_ALLOWED_COLLABORATION_DOMAINS` Returns the list domains that have been deemed safe to create collaborations for within the current enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List box sign requests **Slug:** `BOX_LIST_BOX_SIGN_REQUESTS` Gets signature requests created by a user. If the `sign_files` and/or `parent_folder` are deleted, the signature request will not return in the list. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | | `senders` | array | No | A list of sender emails to filter the signature requests by sender. If provided, `shared_requests` must be set to `true`. | | `shared_requests` | boolean | No | If set to `true`, only includes requests that user is not an owner, but user is a collaborator. Collaborator access is determined by the user access level of the sign files of the request. Default is `false`. Must be set to `true` if `senders` are provided. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List box sign templates **Slug:** `BOX_LIST_BOX_SIGN_TEMPLATES` Gets Box Sign templates created by a user. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List box skill cards on file **Slug:** `BOX_LIST_BOX_SKILL_CARDS_ON_FILE` List the Box Skills metadata cards that are attached to a file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List collection items **Slug:** `BOX_LIST_COLLECTION_ITEMS` Retrieves the files and/or folders contained within a Box collection. Collections in Box are used to organize content. Currently, Box supports one type of collection: 'Favorites', which allows users to mark files and folders for quick access. Use this action to: - List all files and folders in a user's Favorites collection - Paginate through large collections using offset and limit parameters - Request specific fields to reduce response size Note: To get the collection_id, first use the 'List all collections' action (BOX_LIST_ALL_COLLECTIONS). #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Default is 100 if not specified. The maximum allowed value is 1000. | | `fields` | array | No | A list of attribute names to include in the response (e.g., ['name', 'id', 'created_at', 'modified_at']). When specified, only the requested fields are returned along with the mini representation fields. If not specified, standard fields are returned. Available fields include: name, id, type, created_at, modified_at, description, size, path_collection, etc. | | `offset` | integer | No | The zero-based offset of the first item to return. Used for pagination. Maximum value is 10000; requests with offset > 10000 will be rejected with a 400 error. Default is 0. | | `collection_id` | string | Yes | The unique identifier of the collection. Use the 'List all collections' action (BOX_LIST_ALL_COLLECTIONS) to retrieve available collection IDs. Box currently supports one collection type: 'Favorites'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List enterprise device pins **Slug:** `BOX_LIST_ENTERPRISE_DEVICE_PINS` Retrieves all the device pins within an enterprise. The user must have admin privileges, and the application needs the "manage enterprise" scope to make this call. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | | `direction` | string ("ASC" | "DESC") | No | The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. | | `enterprise_id` | string | Yes | The ID of the enterprise | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List groups for enterprise **Slug:** `BOX_LIST_ENTERPRISE_GROUPS` Retrieves all of the groups for a given enterprise. The user must have admin permissions to inspect enterprise's groups. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | 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. | | `offset` | integer | No | The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | | `filter_term` | string | No | Limits the results to only groups whose `name` starts with the search term. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List all metadata templates for enterprise **Slug:** `BOX_LIST_ENTERPRISE_METADATA_TEMPLATES` Used to retrieve all metadata templates created to be used specifically within the user's enterprise #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List enterprise users **Slug:** `BOX_LIST_ENTERPRISE_USERS` Returns a list of all users for the Enterprise along with their `user_id`, `public_name`, and `login`. The application and the authenticated user need to have the permission to look up users in the entire enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | 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. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | | `offset` | integer | No | The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | | `usemarker` | boolean | No | Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response. | | `user_type` | string ("all" | "external" | "managed") | No | Limits the results to the kind of user specified. * `all` returns every kind of user for whom the `login` or `name` partially matches the `filter_term`. It will only return an external user if the login matches the `filter_term` completely, and in that case it will only return that user. * `managed` returns all managed and app users for whom the `login` or `name` partially matches the `filter_term`. * `external` returns all external users for whom the `login` matches the `filter_term` exactly. | | `filter_term` | string | No | Limits the results to only users who"s `name` or `login` start with the search term. For externally managed users, the search term needs to completely match the in order to find the user, and it will only return one user at a time. | | `external_app_user_id` | string | No | Limits the results to app users with the given `external_app_user_id` value. When creating an app user, an `external_app_user_id` value can be set. This value can then be used in this endpoint to find any users that match that `external_app_user_id` value. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List user and enterprise events **Slug:** `BOX_LIST_EVENTS` Returns up to a year of past events for a given user or for the entire enterprise. By default this returns events for the authenticated user. To retrieve events for the entire enterprise, set the `stream_type` to `admin_logs_streaming` for live monitoring of new events, or `admin_logs` for querying across historical events. The user making the API call will need to have admin privileges, and the application will need to have the scope `manage enterprise properties` checked. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Limits the number of events returned Note: Sometimes, the events less than the limit requested can be returned even when there may be more events remaining. This is primarily done in the case where a number of events have already been retrieved and these retrieved events are returned rather than delaying for an unknown amount of time to see if there are any more results. | | `event_type` | array | No | A comma-separated list of events to filter by. This can only be used when requesting the events with a `stream_type` of `admin_logs` or `adming_logs_streaming`. For any other `stream_type` this value will be ignored. | | `stream_type` | string ("admin_logs" | "admin_logs_streaming" | "all" | "changes" | "sync") | No | Defines the type of events that are returned * `all` returns everything for a user and is the default * `changes` returns events that may cause file tree changes such as file updates or collaborations. * `sync` is similar to `changes` but only applies to synced folders * `admin_logs` returns all events for an entire enterprise and requires the user making the API call to have admin permissions. This stream type is for programmatically pulling from a 1 year history of events across all users within the enterprise and within a `created_after` and `created_before` time frame. The complete history of events will be returned in chronological order based on the event time, but latency will be much higher than `admin_logs_streaming`. * `admin_logs_streaming` returns all events for an entire enterprise and requires the user making the API call to have admin permissions. This stream type is for polling for recent events across all users within the enterprise. Latency will be much lower than `admin_logs`, but events will not be returned in chronological order and may contain duplicates. | | `created_after` | string | No | The lower bound date and time to return events for. This can only be used when requesting the events with a `stream_type` of `admin_logs`. For any other `stream_type` this value will be ignored. | | `created_before` | string | No | The upper bound date and time to return events for. This can only be used when requesting the events with a `stream_type` of `admin_logs`. For any other `stream_type` this value will be ignored. | | `stream_position` | string | No | The location in the event stream to start receiving events from. * `now` will return an empty list events and the latest stream position for initialization. * `0` or `null` will return all events. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List file app item associations **Slug:** `BOX_LIST_FILE_APP_ITEM_ASSOCIATIONS` **This is a beta feature, which means that its availability might be limited.** Returns all app items the file is associated with. This includes app items associated with ancestors of the file. Assuming the context user has access to the file, the type/ids are revealed even if the context user does not have **View** permission on the app item. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Default is 10, maximum is 100. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. Use the `next_marker` value from a previous response to get the next page of results. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `application_type` | string | No | If specified, only return app items for this application type. Example values include 'hubs' for Box Hubs associations. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List file collaborations **Slug:** `BOX_LIST_FILE_COLLABORATIONS` Retrieves a list of pending and active collaborations for a file. This returns all the users that have access to the file or have been invited to the file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | 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. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. Use the 'next_marker' value from a previous response to retrieve the next page of results. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List file comments **Slug:** `BOX_LIST_FILE_COMMENTS` Retrieves a list of comments for a file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | 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. | | `offset` | integer | No | The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Review files on legal hold policy assignment **Slug:** `BOX_LIST_FILES_ON_LEGAL_HOLD_POLICY_ASSIGNMENT` Get a list of files with current file versions for a legal hold assignment. In some cases you may want to get previous file versions instead. In these cases, use the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold` API instead to return any previous versions of a file for this legal hold policy assignment. Due to ongoing re-architecture efforts this API might not return all file versions held for this policy ID. Instead, this API will only return the latest file version held in the newly developed architecture. The `GET /file_version_legal_holds` API can be used to fetch current and past versions of files held within the legacy architecture. This endpoint does not support returning any content that is on hold due to a Custodian collaborating on a Hub. The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Default is determined by the API. Maximum allowed value is 1000. | | `fields` | array | No | A comma-separated list of attributes to include in the response. Use this to request specific fields beyond the default mini representation. Common fields include: id, type, name, sha1, file_version. Note: Specifying fields returns only mini representation plus the requested fields. | | `marker` | string | No | Cursor position for marker-based pagination. Use the 'next_marker' value from a previous response to retrieve the next page of results. | | `legal_hold_policy_assignment_id` | string | Yes | The unique identifier of the legal hold policy assignment. Obtain this ID by listing assignments for a legal hold policy using the 'List legal hold policy assignments' action with a policy_id. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List file version legal holds **Slug:** `BOX_LIST_FILE_VERSION_LEGAL_HOLDS` Get a list of file versions on legal hold for a legal hold assignment. Due to ongoing re-architecture efforts this API might not return all file versions for this policy ID. Instead, this API will only return file versions held in the legacy architecture. Two new endpoints will available to request any file versions held in the new architecture. For file versions held in the new architecture, the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold` API can be used to return all past file versions available for this policy assignment, and the `GET /legal_hold_policy_assignments/:id/files_on_hold` API can be used to return any current (latest) versions of a file under legal hold. The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID. Once the re-architecture is completed this API will be deprecated. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Maximum value is 1000. | | `marker` | string | No | The position marker for pagination. Use the 'next_marker' value from a previous response to retrieve the next page of results. | | `policy_id` | string | Yes | The unique identifier (ID) of the legal hold policy. Use BOX_LIST_ALL_LEGAL_HOLD_POLICIES to retrieve available policy IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List file version retentions **Slug:** `BOX_LIST_FILE_VERSION_RETENTIONS` Retrieves all file version retentions for the given enterprise. **Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](e://get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](e://get-retention-policy-assignments-id-file-versions-under-retention) endpoints. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | | `file_id` | string | No | Filters results by files with this ID. | | `policy_id` | string | No | Filters results by the retention policy with this ID. | | `file_version_id` | string | No | Filters results by file versions with this ID. | | `disposition_after` | string | No | Filters results by files that will have their disposition come into effect after this date. | | `disposition_action` | string ("permanently_delete" | "remove_retention") | No | Filters results by the retention policy with this disposition action. | | `disposition_before` | string | No | Filters results by files that will have their disposition come into effect before this date. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List folder app item associations **Slug:** `BOX_LIST_FOLDER_APP_ITEM_ASSOCIATIONS` **This is a beta feature, which means that its availability might be limited.** Returns all app items the folder is associated with. This includes app items associated with ancestors of the folder. Assuming the context user has access to the folder, the type/ids are revealed even if the context user does not have **View** permission on the app item. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Maximum value is 1000. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. The value should be taken from the `next_marker` field returned in a previous response. | | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `application_type` | string | No | If given, returns only app items for this application type. Example values include 'hubs' for Box Hubs associations. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List folder collaborations **Slug:** `BOX_LIST_FOLDER_COLLABORATIONS` Retrieves a list of pending and active collaborations for a folder. This returns all the users that have access to the folder or have been invited to the folder. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | 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. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination to retrieve the next page of results. | | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List folder locks **Slug:** `BOX_LIST_FOLDER_LOCKS` Retrieves folder lock details for a given folder. You must be authenticated as the owner or co-owner of the folder to use this endpoint. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier of the folder to list locks for. The ID for any folder can be determined by visiting the folder in the Box web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. Note: The root folder (ID `0`) does not support folder locks. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List group collaborations **Slug:** `BOX_LIST_GROUP_COLLABORATIONS` Retrieves all the collaborations for a group. The user must have admin permissions to inspect enterprise's groups. Each collaboration object has details on which files or folders the group has access to and with what role. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Default is 100, maximum is 1000. | | `offset` | integer | No | The offset of the item at which to begin the response. Use for pagination. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | | `group_id` | string | Yes | The unique identifier of the group. Use the 'List groups for enterprise' action to retrieve available group IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List members of group **Slug:** `BOX_LIST_GROUP_MEMBERS` Retrieves all the members for a group. Only members of this group or users with admin-level permissions will be able to use this API. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Maximum value is 1000. | | `offset` | integer | No | The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | | `group_id` | string | Yes | The ID of the group. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List previous file versions for legal hold policy assignment **Slug:** `BOX_LIST_HOLD_FILE_VERSIONS` Retrieves a list of previous (non-current) file versions that are on legal hold for a specific legal hold policy assignment. This endpoint returns file versions held under the new Box architecture. For current (latest) file versions, use BOX_REVIEW_FILES_ON_LEGAL_HOLD_POLICY_ASSIGNMENT instead. For file versions in the legacy architecture, use BOX_LIST_FILE_VERSION_LEGAL_HOLDS. Note: Due to ongoing re-architecture efforts, this API might not return all file versions held for this policy ID. This endpoint does not support returning content that is on hold due to a Custodian collaborating on a Hub. Requires the 'manage_legal_holds' scope and Legal Hold feature enabled for the enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Maximum value is 1000. | | `fields` | array | No | A comma-separated list of attributes to include in the response. Use this to request specific fields like 'id', 'sha1', 'name', 'size', etc. If specified, only the requested fields plus mini representation fields are returned. | | `marker` | string | No | The position marker for pagination. Use the 'next_marker' value from a previous response to retrieve the next page of results. | | `legal_hold_policy_assignment_id` | string | Yes | The unique identifier (ID) of the legal hold policy assignment. This ID is returned when creating an assignment via BOX_ASSIGN_LEGAL_HOLD_POLICY or can be obtained by listing assignments with BOX_LIST_LEGAL_HOLD_POLICY_ASSIGNMENTS. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List Box Hubs **Slug:** `BOX_LIST_HUBS` Tool to list all Box Hubs for the authenticated user or enterprise. Use when you need to retrieve, search, or filter Box Hubs. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sort` | string ("name" | "updated_at" | "last_accessed_at" | "view_count" | "relevance") | No | Field to sort results by | | `limit` | integer | No | The maximum number of items to return per page. | | `query` | string | No | The query string to search for Box Hubs. | | `scope` | string ("editable" | "view_only" | "all") | No | Scope of Box Hubs to retrieve | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. | | `direction` | string ("ASC" | "DESC") | No | Sort direction | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List items in folder **Slug:** `BOX_LIST_ITEMS_IN_FOLDER` Retrieves a page of items in a folder. These items can be files, folders, and web links. To request more information about the folder itself, like its size, use the [Get a folder](#get-folders-id) endpoint instead. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sort` | string ("date" | "id" | "name" | "size") | No | Defines the **second** attribute by which items are sorted. The folder type affects the way the items are sorted: * **Standard folder**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. * **Root folder**: This parameter is not supported for marker-based pagination on the root folder (the folder with an `id` of `0`). * **Shared folder with parent path to the associated folder visible to the collaborator**: Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. | | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | 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. Additionally this field can be used to query any metadata applied to the file by specifying the `metadata` field as well as the scope and key of the template to retrieve, for example `?fields=metadata.enterprise_12345.contractTemplate`. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | | `offset` | integer | No | The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | | `direction` | string ("ASC" | "DESC") | No | The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. | | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `usemarker` | boolean | No | Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List all legal hold policies **Slug:** `BOX_LIST_LEGAL_HOLD_POLICIES` Retrieves a list of legal hold policies that belong to an enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | 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. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | | `policy_name` | string | No | Limits results to policies for which the names start with this search term. This is a case-insensitive prefix. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List legal hold policy assignments **Slug:** `BOX_LIST_LEGAL_HOLD_POLICY_ASSIGNMENTS` Retrieves a list of items a legal hold policy has been assigned to. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Maximum value is 1000. | | `fields` | array | No | 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. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. | | `policy_id` | string | Yes | The ID of the legal hold policy | | `assign_to_id` | string | No | Filters the results by the ID of item the policy was applied to. Must be used together with assign_to_type. | | `assign_to_type` | string ("file" | "file_version" | "folder" | "user") | No | Type of item the legal hold policy can be assigned to. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List metadata cascade policies **Slug:** `BOX_LIST_METADATA_CASCADE_POLICIES` Retrieves a list of all the metadata cascade policies that are applied to a given folder. This can not be used on the root folder with ID `0`. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | | `offset` | integer | No | The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | | `folder_id` | string | Yes | Specifies which folder to return policies for. This can not be used on the root folder with ID `0`. | | `owner_enterprise_id` | string | No | The ID of the enterprise ID for which to find metadata cascade policies. If not specified, it defaults to the current enterprise. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List metadata instances on file **Slug:** `BOX_LIST_METADATA_INSTANCES_ON_FILE` Retrieves all metadata instances applied to a file. Returns all metadata template instances that have been applied to the specified file, including both enterprise and global templates. The API does not support pagination and will return all metadata instances in a single response. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List metadata instances on folder **Slug:** `BOX_LIST_METADATA_INSTANCES_ON_FOLDER` Retrieves all metadata for a given folder. This can not be used on the root folder with ID `0`. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List metadata taxonomy nodes **Slug:** `BOX_LIST_METADATA_TAXONOMY_NODES` Retrieves metadata taxonomy nodes based on the specified parameters. Use when you need to browse or search hierarchical metadata classifications in Box. Results are sorted in lexicographic order unless a query parameter is passed, in which case results are sorted by relevance. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `level` | array | No | Filters results by taxonomy level. Multiple values can be provided. Results include nodes that match any of the specified values. | | `limit` | integer | No | The maximum number of items to return per page. | | `query` | string | No | Query text to search for the taxonomy nodes. When specified, results are sorted by relevance instead of lexicographic order. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires usemarker to be set to true. | | `parent` | array | No | Node identifier of a direct parent node. Multiple values can be provided. Results include nodes that match any of the specified values. | | `ancestor` | array | No | Node identifier of any ancestor node. Multiple values can be provided. Results include nodes that match any of the specified values. | | `namespace` | string | Yes | The namespace of the metadata taxonomy. Typically starts with 'enterprise_' followed by your enterprise ID. | | `taxonomy_key` | string | Yes | The key of the metadata taxonomy. This is the unique identifier for the taxonomy template. | | `include-total-result-count` | boolean | No | When set to true, provides the total number of nodes that matched the query. The response will compute counts of up to 10,000 elements. Defaults to false. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List pending collaborations **Slug:** `BOX_LIST_PENDING_COLLABORATIONS` Retrieves all pending collaboration invites for this user. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Maximum value is 1000. | | `fields` | array | No | A list of attributes to include in the response (e.g., ['id', 'type', 'status']). 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. Common fields include: id, type, status, role, created_at, modified_at, expires_at, invite_email, accessible_by, item. | | `offset` | integer | No | The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | | `status` | string ("pending") | No | The status of the collaborations to retrieve. Must be 'pending'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List recently accessed items **Slug:** `BOX_LIST_RECENTLY_ACCESSED_ITEMS` Returns information about the recent items accessed by a user, either in the last 90 days or up to the last 1000 items accessed. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | 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. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List retention policies **Slug:** `BOX_LIST_RETENTION_POLICIES` Retrieves all of the retention policies for an enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | 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. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. | | `policy_name` | string | No | Filters results by a case sensitive prefix of the name of retention policies. | | `policy_type` | string ("finite" | "indefinite") | No | Filters results by the type of retention policy. | | `created_by_user_id` | string | No | Filters results by the ID of the user who created policy. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List retention policy assignments **Slug:** `BOX_LIST_RETENTION_POLICY_ASSIGNMENTS` Retrieves all retention policy assignments for a specified retention policy. Retention policies can be assigned to: - 'enterprise': Apply to all content in the enterprise - 'folder': Apply to a specific folder - 'metadata_template': Apply based on metadata template values Requires the 'manage_retention_policies' scope. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string ("enterprise" | "folder" | "metadata_template") | No | The type of retention policy assignment to filter by. | | `limit` | integer | No | Maximum number of assignments to return per page. Maximum value is 1000. | | `fields` | array | No | A comma-separated list of additional fields to include in the response. Useful for requesting fields not returned by default. When specified, only mini representation fields plus the requested fields are returned. | | `marker` | string | No | Pagination marker from a previous response's 'next_marker' field. Used to fetch the next page of results. | | `retention_policy_id` | string | Yes | The unique identifier of the retention policy to list assignments for. This ID can be obtained from the list retention policies endpoint. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List shield information barrier reports **Slug:** `BOX_LIST_SHIELD_INFORMATION_BARRIER_REPORTS` Lists shield information barrier reports for a specified barrier. Shield information barrier reports contain details about barrier violations and compliance status. This feature requires Box Shield enterprise license. Returns a paginated list of report objects with status (pending/completed), creation timestamps, and details about the barrier scope. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Maximum value is 1000. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. | | `shield_information_barrier_id` | string | Yes | The unique identifier of the shield information barrier. This ID can be obtained from the 'List shield information barriers' action. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List shield information barriers **Slug:** `BOX_LIST_SHIELD_INFORMATION_BARRIERS` Retrieves a list of shield information barrier objects for the enterprise of JWT. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List shield information barrier segment members **Slug:** `BOX_LIST_SHIELD_INFORMATION_BARRIER_SEGMENT_MEMBERS` Lists shield information barrier segment members based on provided segment IDs. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Maximum value is 1000. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. Use the value from `next_marker` in the previous response to get the next page. | | `shield_information_barrier_segment_id` | string | Yes | The ID of the shield information barrier segment. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List shield information barrier segment restrictions **Slug:** `BOX_LIST_SHIELD_INFORMATION_BARRIER_SEGMENT_RESTRICTIONS` Lists all shield information barrier segment restrictions for a specific segment. Shield information barrier segment restrictions define which segments are prevented from collaborating with each other. This endpoint retrieves all restrictions where the specified segment is the requesting segment (the segment whose members are restricted from collaborating with other segments). Note: This feature requires Box Shield add-on and enterprise admin privileges. Returns 404 if Shield is not enabled for your enterprise or if the segment ID does not exist. Use Cases: - View all collaboration restrictions for a specific segment - Audit compliance boundaries between organizational divisions - Paginate through large sets of restrictions using marker-based pagination #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Maximum number of restriction items to return per page. Valid range is 1-1000. If not specified, the API uses its default page size. | | `marker` | string | No | Pagination marker from a previous response's 'next_marker' field. Used to retrieve the next page of results when paginating through large result sets. | | `shield_information_barrier_segment_id` | string | Yes | The unique identifier of the shield information barrier segment to list restrictions for. Obtain this ID from the list_shield_information_barrier_segments or create_shield_information_barrier_segment actions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List shield information barrier segments **Slug:** `BOX_LIST_SHIELD_INFORMATION_BARRIER_SEGMENTS` Retrieves a list of shield information barrier segment objects for the specified Information Barrier ID. Shield Information Barriers are used to separate individuals/groups within the same enterprise to prevent confidential information from passing between them. Segments define the groups of users that are separated by the barrier. Note: This is an enterprise-level feature that requires Box Shield to be enabled. Returns a 404 error if Shield Information Barriers is not available for the enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. Maximum value is 1000. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. Use the next_marker value from a previous response to fetch the next page of results. | | `shield_information_barrier_id` | string | Yes | The ID of the shield information barrier to retrieve segments for. This is a required parameter obtained from list or create shield information barrier actions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List slack integration mappings **Slug:** `BOX_LIST_SLACK_INTEGRATION_MAPPINGS` Lists [Slack integration mappings](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) in a users' enterprise. You need Admin or Co-Admin role to use this endpoint. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | | `box_item_id` | string | No | Box item ID, for which the mappings should be returned | | `box_item_type` | string ("folder") | No | Box item type, for which the mappings should be returned | | `partner_item_id` | string | No | ID of the mapped item, for which the mapping should be returned | | `partner_item_type` | string ("channel") | No | Mapped item type, for which the mapping should be returned | | `is_manually_created` | boolean | No | Whether the mapping has been manually created | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List storage policies **Slug:** `BOX_LIST_STORAGE_POLICIES` Fetches all the storage policies in the enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | 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. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List storage policy assignments **Slug:** `BOX_LIST_STORAGE_POLICY_ASSIGNMENTS` Fetches all the storage policy assignment for an enterprise or user. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | | `resolved_for_id` | string | Yes | The ID of the user or enterprise to return assignments for | | `resolved_for_type` | string ("enterprise" | "user") | Yes | The target type to return assignments for | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List task assignments **Slug:** `BOX_LIST_TASK_ASSIGNMENTS` Lists all of the assignments for a given task. Returns a collection of task assignment objects showing who has been assigned to complete or review a task. Each assignment includes the assigned user's details, the assignment status, and the associated file information. This endpoint does not support pagination as tasks typically have a limited number of assignees. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_id` | string | Yes | The unique identifier of the task to retrieve assignments for. Task IDs can be obtained from the 'create_task' or 'list_tasks_on_file' actions. Example: '39641675308'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List tasks on file **Slug:** `BOX_LIST_TASKS_ON_FILE` Retrieves a list of all the tasks for a file. This endpoint does not support pagination. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List teams integration mappings **Slug:** `BOX_LIST_TEAMS_INTEGRATION_MAPPINGS` Lists [Teams integration mappings](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams) in a users' enterprise. You need Admin or Co-Admin role to use this endpoint. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `box_item_id` | string | No | Box item ID, for which the mappings should be returned | | `box_item_type` | string ("folder") | No | Box item type, for which the mappings should be returned | | `partner_item_id` | string | No | ID of the mapped item, for which the mapping should be returned | | `partner_item_type` | string ("channel" | "team") | No | Mapped item type, for which the mapping should be returned | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List terms of services **Slug:** `BOX_LIST_TERMS_OF_SERVICES` Returns the current terms of service text and settings for the enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tos_type` | string ("external" | "managed") | No | Limits the results to the terms of service of the given type. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List terms of service user statuses **Slug:** `BOX_LIST_TERMS_OF_SERVICE_USER_STATUSES` Retrieves a list of users and their acceptance status for a specific terms of service. Returns information about whether each user has accepted the terms, including: - User details (ID, name, email) - Acceptance status (accepted or not) - Creation and modification timestamps Note: This endpoint requires the Terms of Service feature to be enabled for the enterprise and appropriate admin permissions (manage enterprise properties or manage users). Use 'list_terms_of_services' first to get valid terms of service IDs. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tos_id` | string | Yes | The unique identifier of the terms of service to retrieve user statuses for. Use 'list_terms_of_services' action to find available terms of service IDs for your enterprise. | | `user_id` | string | No | Optional. Filters results to show only the status for a specific user. If not provided, returns statuses for all users associated with the terms of service. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List trashed items **Slug:** `BOX_LIST_TRASHED_ITEMS` Retrieves the files and folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the `fields` parameter to retrieve those specific attributes that are not returned by default. This endpoint defaults to use offset-based pagination, yet also supports marker-based pagination using the `marker` parameter. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sort` | string ("date" | "name" | "size") | No | Defines the **second** attribute by which items are sorted. Items are always sorted by their `type` first, with folders listed before files, and files listed before web links. This parameter is not supported when using marker-based pagination. | | `limit` | integer | No | The maximum number of items to return per page. | | `fields` | array | No | 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. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | | `offset` | integer | No | The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | | `direction` | string ("ASC" | "DESC") | No | The direction to sort results in. This can be either in alphabetical ascending (`ASC`) or descending (`DESC`) order. | | `usemarker` | boolean | No | Specifies whether to use marker-based pagination instead of offset-based pagination. Only one pagination method can be used at a time. By setting this value to true, the API will return a `marker` field that can be passed as a parameter to this endpoint to get the next page of the response. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List upload session parts **Slug:** `BOX_LIST_UPLOAD_SESSION_PARTS` List the parts (chunks) that have been uploaded to a chunked upload session. This is useful for tracking upload progress, verifying which parts have been successfully uploaded, and determining which parts still need to be uploaded. The upload_session_id is obtained from the 'Create upload session' action. Note: Chunked uploads are only for files larger than 20MB. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of parts to return per page. Maximum allowed value is 1000. If not specified, the server default is used. | | `offset` | integer | No | The zero-based offset of the first part to return. Used for pagination. Default is 0. Note: Queries with offset exceeding 10000 will be rejected with a 400 response. | | `upload_session_id` | string | Yes | The unique identifier of the chunked upload session. This ID is returned when creating an upload session via the 'Create upload session' endpoint. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List user's email aliases **Slug:** `BOX_LIST_USER_EMAIL_ALIASES` Retrieves all email aliases for a user. The collection does not include the primary login for the user. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `user_id` | string | Yes | The ID of the user. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List user's groups **Slug:** `BOX_LIST_USER_GROUPS` Retrieves all group memberships for a user, including the groups they belong to and their role in each group (member or admin). Only members of this group or users with admin-level permissions will be able to use this API. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `offset` | integer | No | The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | | `user_id` | string | Yes | The ID of the user. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List users exempt from collaboration domain restrictions **Slug:** `BOX_LIST_USERS_EXEMPT_FROM_COLLABORATION_DOMAIN_RESTRICTIONS` Returns a list of users who have been exempt from the collaboration domain restrictions. Note: This endpoint requires an enterprise account with collaboration domain restrictions enabled. A 403 Forbidden error will be returned if the feature is not available for the enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of items to return per page. | | `marker` | string | No | Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List all webhooks **Slug:** `BOX_LIST_WEBHOOKS` Returns all defined webhooks for the requesting application. This API only returns webhooks that are applied to files or folders that are owned by the authenticated user. This means that an admin can not see webhooks created by a service account unless the admin has access to those folders, and vice versa. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Maximum number of webhooks to return per page. The Box API uses 100 as default if not specified. Must be a positive integer. | | `marker` | string | No | Pagination marker from a previous response's 'next_marker' field. Use this to retrieve the next page of results when paginating through webhooks. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### List workflows **Slug:** `BOX_LIST_WORKFLOWS` Lists Box Relay workflows configured for a specific folder. Use the 'trigger_type' parameter to filter workflows by trigger type (e.g., 'WORKFLOW_MANUAL_START' for workflows that can be manually started via API). Your application must be authorized to use the 'Manage Box Relay' application scope within the Box developer console. Returns a paginated list of workflow objects with their flows and outcomes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | The maximum number of workflows to return per page. If not specified, the API uses a default page size (typically 20). Maximum value varies by API. | | `marker` | string | No | Defines the position marker at which to begin returning results. Used for cursor-based pagination. Obtain this value from the 'next_marker' field in a previous response to fetch the next page of results. | | `folder_id` | string | Yes | The unique identifier of the folder to list workflows for. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `trigger_type` | string | No | Type of trigger to filter workflows by. Use 'WORKFLOW_MANUAL_START' to find workflows that can be manually triggered via the API. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Preflight check before upload **Slug:** `BOX_PREFLIGHT_CHECK_BEFORE_UPLOAD` Performs a preflight check to verify that a file will be accepted by Box before uploading the entire file. This helps verify permissions, quota, and filename conflicts before starting the actual upload. A successful response (HTTP 200) indicates the upload can proceed. A 409 Conflict response indicates a file with the same name already exists. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | The name for the file to be uploaded. Must be unique within the target folder. | | `size` | integer | No | The size of the file in bytes. Used to verify storage quota availability. | | `parent_id` | string | No | The ID of the parent folder where the file will be uploaded. Use '0' for the root folder. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Promote file version **Slug:** `BOX_PROMOTE_FILE_VERSION` Promote a specific version of a file. If previous versions exist, this method can be used to promote one of the older versions to the top of the version history. This creates a new copy of the old version and puts it at the top of the versions history. The file will have the exact same contents as the older version, with the the same hash digest, `etag`, and name as the original. Other properties such as comments do not get updated to their former values. Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | string | Yes | The ID of the file version to promote to the current version. You can get file version IDs by calling the 'list_all_file_versions' action with the file_id. This creates a new copy of the specified version at the top of the version history. | | `type` | string ("file_version") | No | The type of item being promoted. Must be 'file_version'. Defaults to 'file_version' if not specified. | | `fields` | array | No | 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. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Query files folders by metadata **Slug:** `BOX_QUERY_FILES_FOLDERS_BY_METADATA` Query files and folders by metadata using SQL-like syntax. Returns items that have metadata instances matching the specified template and optional query conditions. Use this action when you need to find files/folders based on their metadata values rather than searching by file name or content. This is useful for locating documents based on custom attributes like status, category, department, dates, etc. Examples: - Find all files with a specific metadata template: set `from_` to "enterprise_XXXXX.templateKey" - Find files in a specific folder: set `ancestor_folder_id` to the folder ID (use "0" for all folders) - Filter by metadata values: use `query` and `query_params` (e.g., query="status = :val", query_params={"val": "approved"}) Note: Classification templates cannot be queried with this endpoint. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `from` | string | Yes | The metadata template to query. Must be in the form 'scope.templateKey'. For enterprise templates, use 'enterprise_XXXXX.templateKey' where XXXXX is your enterprise ID. For example: 'enterprise_1351007304.contractTemplate'. Note: Box-provided classification templates cannot be used with this endpoint. Use BOX_LIST_ALL_METADATA_TEMPLATES_FOR_ENTERPRISE to find available templates. | | `limit` | integer | No | A value between 0 and 100 that indicates the maximum number of results to return for a single request. This only specifies a maximum boundary and will not guarantee the minimum number of results returned. | | `query` | string | No | Optional SQL-like filter expression to match metadata field values. Use parameterized values with ':' prefix (e.g., ':value') that map to query_params. Examples: 'status = :val', 'amount >= :min AND amount <= :max', 'category LIKE :pattern'. Supported operators: =, <, >, <=, >=, <>, LIKE, NOT LIKE, ILIKE, NOT ILIKE, IS NULL, IS NOT NULL. If omitted, returns all items with the specified metadata template. | | `fields` | array | No | By default, this endpoint returns only the most basic info about the items for which the query matches. This attribute can be used to specify a list of additional attributes to return for any item, including its metadata. This attribute takes a list of item fields, metadata template identifiers, or metadata template field identifiers. For example: * `created_by` will add the details of the user who created the item to the response. * `metadata..` will return the mini-representation of the metadata instance identified by the `scope` and `templateKey`. * `metadata...` will return all the mini-representation of the metadata instance identified by the `scope` and `templateKey` plus the field specified by the `field` name. Multiple fields for the same `scope` and `templateKey` can be defined. | | `marker` | string | No | Pagination marker from a previous response's 'next_marker' field. Use this to retrieve the next page of results when the previous response included a next_marker. | | `order_by` | array | No | A list of template fields and directions to sort the metadata query results by. The ordering `direction` must be the same for each item in the array. | | `query_params` | object | No | Key-value pairs for parameterized values used in the 'query' expression. Keys must match the parameter names in query (without ':'). Example: if query='status = :val', then query_params={'val': 'approved'}. Value types must match the metadata template field types (string, float, date, etc.). | | `ancestor_folder_id` | string | Yes | The folder ID to search within. Use '0' to search all folders accessible to the user. Use a specific folder ID to limit results to that folder and its subfolders. Example: '0' for root/all folders, or '12345' for a specific folder. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Refresh access token **Slug:** `BOX_REFRESH_ACCESS_TOKEN` Refresh an Access Token using its client ID, secret, and refresh token. This endpoint exchanges a refresh token for a new access token. The refresh token must be valid (they expire after 60 days). Each time a refresh token is used, it is invalidated and a new one is returned along with the new access token. Access tokens expire after 1 hour and need to be refreshed periodically. Note: This action requires valid OAuth2 credentials (client_id, client_secret, and a valid refresh_token) that cannot be automatically generated. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `client_id` | string | Yes | The client ID of the Box OAuth2 application requesting the token refresh. | | `grant_type` | string ("refresh_token") | No | The type of OAuth2 grant being requested. Must be 'refresh_token' for this endpoint. | | `client_secret` | string | Yes | The client secret of the Box OAuth2 application requesting the token refresh. | | `refresh_token` | string | Yes | The refresh token to exchange for a new access token. Each refresh token can only be used once. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Request access token **Slug:** `BOX_REQUEST_ACCESS_TOKEN` Request an Access Token using either a client-side obtained OAuth 2.0 authorization code or a server-side JWT assertion. An Access Token is a string that enables Box to verify that a request belongs to an authorized session. In the normal order of operations you will begin by requesting authentication from the [authorize](#get-authorize) endpoint and Box will send you an authorization code. You will then send this code to this endpoint to exchange it for an Access Token. The returned Access Token can then be used to to make Box API calls. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `code` | string | No | The client-side authorization code passed to your application by Box in the browser redirect after the user has successfully granted your application permission to make API calls on their behalf. Used in combination with `authorization_code` as the `grant_type`. | | `scope` | string | No | The space-delimited list of scopes that you want apply to the new access token. The `subject_token` will need to have all of these scopes or the call will error with **401 Unauthorized**. | | `resource` | string | No | Full URL for the file that the token should be generated for. | | `assertion` | string | No | A JWT assertion for which to request a new access token. Used in combination with `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`. | | `client_id` | string | No | The Client ID of the application requesting an access token. Used in combination with `authorization_code`, `client_credentials`, or `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`. | | `grant_type` | string ("authorization_code" | "client_credentials" | "refresh_token" | "urn:ietf:params:oauth:grant-type:jwt-bearer" | "urn:ietf:params:oauth:grant-type:token-exchange") | Yes | The type of request being made, either using a client-side obtained authorization code, a refresh token, a JWT assertion, client credentials grant or another access token for the purpose of downscoping a token. | | `actor_token` | string | No | The token used to create an annotator token. This is a JWT assertion. Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`. | | `client_secret` | string | No | The client secret of the application requesting an access token. Used in combination with `authorization_code`, `client_credentials`, or `urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`. | | `refresh_token` | string | No | A refresh token used to get a new access token with. Used in combination with `refresh_token` as the `grant_type`. | | `subject_token` | string | No | The token to exchange for a downscoped token. This can be a regular access token, a JWT assertion, or an app token. Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`. | | `box_subject_id` | string | No | Used in combination with `client_credentials` as the `grant_type`. Value is determined by `box_subject_type`. If `user` use user ID and if `enterprise` use enterprise ID. | | `box_shared_link` | string | No | Full URL of the shared link on the file or folder that the token should be generated for. | | `actor_token_type` | string ("urn:ietf:params:oauth:token-type:id_token") | No | The type of `actor_token` passed in. Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`. | | `box_subject_type` | string ("enterprise" | "user") | No | Used in combination with `client_credentials` as the `grant_type`. | | `subject_token_type` | string ("urn:ietf:params:oauth:token-type:access_token") | No | The type of `subject_token` passed in. Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange` as the `grant_type`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Resend Box Sign Request **Slug:** `BOX_RESEND_BOX_SIGN_REQUEST` Resends signature request emails to all outstanding signers. Use this when a signer did not receive the original email, the email was lost, or the signer accidentally deleted it. The email is sent asynchronously after the API call returns. Rate limit: Can only be called once every 10 minutes per sign request. Note: For automated reminders, consider setting 'are_reminders_enabled' to true when creating the sign request, which sends automatic reminder emails after 3, 8, 13, and 18 days. Requires Box Sign feature to be enabled and sign_requests.readwrite scope. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sign_request_id` | string | Yes | The unique identifier (UUID) of the Box Sign request to resend. This ID can be obtained from the response when creating a sign request or by listing all sign requests using the list_box_sign_requests action. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Restore file **Slug:** `BOX_RESTORE_FILE` Restores a file that has been moved to the trash. An optional new parent ID can be provided to restore the file to in case the original folder has been deleted. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | An optional new name for the file. | | `fields` | array | No | 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. | | `file_id` | string | Yes | The unique identifier of the trashed file to restore. The file must be in the trash (deleted but not yet purged). The ID can be found by listing trashed items or from the URL in the Box web app (e.g., for `https://*.app.box.com/files/123` the file_id is `123`). Returns 404 if the file is not found in the trash. | | `parent_id` | string | No | The ID of the parent folder to restore the file to. This is useful when the original folder has been deleted. Use '0' for the root folder. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Restore file version **Slug:** `BOX_RESTORE_FILE_VERSION` Restores a specific version of a file after it was deleted (trashed). This action restores a file version that was previously moved to the trash by setting its trashed_at field back to null. Do not use this endpoint to restore Box Notes - it only works with standard file formats such as PDF, DOC, PPTX, or similar. To restore a file version: 1. First use 'List all file versions' to find versions with trashed_at set 2. Then call this action with the file_id and file_version_id The restored version will have trashed_at=null and restored_at/restored_by fields populated. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `file_version_id` | string | Yes | The ID of the file version to restore. Version IDs can be obtained by using the 'List all file versions' action with the file_id. Only versions that have been trashed (trashed_at is not null) can be restored. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Restore folder **Slug:** `BOX_RESTORE_FOLDER` Restores a folder that has been moved to the trash. An optional new parent ID can be provided to restore the folder to in case the original folder has been deleted. During this operation, part of the file tree will be locked, mainly the source folder and all of its descendants, as well as the destination folder. For the duration of the operation, no other move, copy, delete, or restore operation can performed on any of the locked folders. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | An optional new name for the folder. | | `fields` | string | No | A comma-separated list of attributes to include in the response (e.g., 'id,name,size'). 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. | | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `parent__id` | string | No | An optional ID of a folder to restore the folder to when the original folder no longer exists. This ID will only be used if the original folder no longer exists. Use this ID to provide a fallback location to restore the folder to if the original location has been deleted. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Restore web link **Slug:** `BOX_RESTORE_WEB_LINK` Restores a web link that has been moved to the trash. This action recovers a trashed web link and restores it to its original parent folder. If the original folder has been deleted, you can optionally specify an alternative parent folder using the parent_id parameter. You can also rename the web link during restoration using the name parameter. The web link must exist in the trash (not permanently deleted) for this action to succeed. Returns the restored web link with item_status changed from 'trashed' to 'active'. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | An optional new name for the web link. Use this to rename the web link while restoring it. | | `fields` | array | No | A list of attributes to include in the response. Available fields include: id, type, name, url, description, created_at, modified_at, trashed_at, purged_at, item_status, created_by, modified_by, owned_by, parent, path_collection, shared_link, sequence_id, etag. If not specified, returns all standard fields. Note that specifying this parameter returns only mini representation fields plus the requested fields. | | `parent_id` | string | No | The ID of the parent folder to restore the web link to. This is useful when the original parent folder has been deleted. If not specified, the web link will be restored to its original location. Use '0' for the root folder. | | `web_link_id` | string | Yes | The unique identifier of the trashed web link to restore. You can find trashed web link IDs by listing trashed items or using the get trashed web link action. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Revoke access token **Slug:** `BOX_REVOKE_ACCESS_TOKEN` Revoke an active Access Token, effectively logging a user out that has been previously authenticated. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `token` | string | No | The access token to revoke. | | `client_id` | string | No | The Client ID of the application requesting to revoke the access token. | | `client_secret` | string | No | The client secret of the application requesting to revoke an access token. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Search for content **Slug:** `BOX_SEARCH_FOR_CONTENT` Searches for files, folders, web links, and shared files across the users content or across the entire enterprise. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sort` | string ("modified_at" | "relevance") | No | Defines the order in which search results are returned. This API defaults to returning items by relevance unless this parameter is explicitly specified. * `relevance` (default) returns the results sorted by relevance to the query search term. The relevance is based on the occurrence of the search term in the items name, description, content, and additional properties. * `modified_at` returns the results ordered in descending order by date at which the item was last modified. | | `type` | string ("file" | "folder" | "web_link") | No | Limits the search results to any items of this type. This parameter only takes one value. By default the API returns items that match any of these types. * `file` - Limits the search results to files * `folder` - Limits the search results to folders * `web_link` - Limits the search results to web links, also known as bookmarks | | `limit` | integer | No | Defines the maximum number of items to return as part of a page of results. | | `query` | string | No | The string to search for. REQUIRED unless 'mdfilters' is provided. Matched against item names, descriptions, text content, and other fields. Supports operators: "" (exact match), AND, OR, NOT (uppercase only). | | `scope` | string ("enterprise_content" | "user_content") | No | Limits the search results to either the files that the user has access to, or to files available to the entire enterprise. The scope defaults to `user_content`, which limits the search results to content that is available to the currently authenticated user. The `enterprise_content` can be requested by an admin through our support channels. Once this scope has been enabled for a user, it will allow that use to query for content across the entire enterprise and not only the content that they have access to. | | `fields` | array | No | 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. | | `offset` | integer | No | The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response. | | `direction` | string ("ASC" | "DESC") | No | Defines the direction in which search results are ordered. This API defaults to returning items in descending (`DESC`) order unless this parameter is explicitly specified. When results are sorted by `relevance` the ordering is locked to returning items in descending order of relevance, and this parameter is ignored. | | `mdfilters` | array | No | Metadata filters to limit search results. REQUIRED unless 'query' is provided. A list specifying exactly one metadata template to filter by. | | `size_range` | array | No | Limits the search results to any items with a size within a given file size range. This applied to files and folders. Size ranges are defined as comma separated list of a lower and upper byte size limit (inclusive). The upper and lower bound can be omitted to create open ranges. | | `content_types` | array | No | Limits the search results to any items that match the search query for a specific part of the file, for example the file description. Content types are defined as a comma separated lists of Box recognized content types. The allowed content types are as follows. * `name` - The name of the item, as defined by its `name` field. * `description` - The description of the item, as defined by its `description` field. * `file_content` - The actual content of the file. * `comments` - The content of any of the comments on a file or folder. * `tags` - Any tags that are applied to an item, as defined by its `tags` field. | | `trash_content` | string ("all_items" | "non_trashed_only" | "trashed_only") | No | Determines if the search should look in the trash for items. By default, this API only returns search results for items not currently in the trash (`non_trashed_only`). * `trashed_only` - Only searches for items currently in the trash * `non_trashed_only` - Only searches for items currently not in the trash * `all_items` - Searches for both trashed and non-trashed items. | | `owner_user_ids` | array | No | Limits the search results to any items that are owned by the given list of owners, defined as a list of comma separated user IDs. The items still need to be owned or shared with the currently authenticated user for them to show up in the search results. If the user does not have access to any files owned by any of the users an empty result set will be returned. To search across an entire enterprise, we recommend using the `enterprise_content` scope parameter which can be requested with our support team. | | `file_extensions` | array | No | Limits the search results to any files that match any of the provided file extensions. This list is a comma-separated list of file extensions without the dots. | | `created_at_range` | array | No | Limits the search results to any items created within a given date range. Date ranges are defined as comma separated RFC3339 timestamps. If the the start date is omitted (`,2014-05-17T13:35:01-07:00`) anything created before the end date will be returned. If the end date is omitted (`2014-05-15T13:35:01-07:00,`) the current date will be used as the end date instead. | | `deleted_at_range` | array | No | Limits the search results to any items deleted within a given date range. Date ranges are defined as comma separated RFC3339 timestamps. If the the start date is omitted (`2014-05-17T13:35:01-07:00`), anything deleted before the end date will be returned. If the end date is omitted (`2014-05-15T13:35:01-07:00`), the current date will be used as the end date instead. The `trash_content` parameter needs to be set to `trashed_only`. If searching in trash is not performed, then an empty result is returned. Data available from 2023-02-01 onwards. | | `deleted_user_ids` | array | No | Limits the search results to items that were deleted by the given list of users, defined as a list of comma separated user IDs. The `trash_content` parameter needs to be set to `trashed_only`. If searching in trash is not performed, an empty result set is returned. The items need to be owned or shared with the currently authenticated user for them to show up in the search results. If the user does not have access to any files owned by any of the users, an empty result set is returned. Data available from 2023-02-01 onwards. | | `updated_at_range` | array | No | Limits the search results to any items updated within a given date range. Date ranges are defined as comma separated RFC3339 timestamps. If the start date is omitted (`,2014-05-17T13:35:01-07:00`) anything updated before the end date will be returned. If the end date is omitted (`2014-05-15T13:35:01-07:00,`) the current date will be used as the end date instead. | | `ancestor_folder_ids` | array | No | Limits the search results to items within the given list of folders, defined as a comma separated lists of folder IDs. Search results will also include items within any subfolders of those ancestor folders. The folders still need to be owned or shared with the currently authenticated user. If the folder is not accessible by this user, or it does not exist, a `HTTP 404` error code will be returned instead. To search across an entire enterprise, we recommend using the `enterprise_content` scope parameter which can be requested with our support team. | | `recent_updater_user_ids` | array | No | Limits the search results to any items that have been updated by the given list of users, defined as a list of comma separated user IDs. The items still need to be owned or shared with the currently authenticated user for them to show up in the search results. If the user does not have access to any files owned by any of the users an empty result set will be returned. This feature only searches back to the last 10 versions of an item. | | `include_recent_shared_links` | boolean | No | Defines whether the search results should include any items that the user recently accessed through a shared link. When this parameter has been set to true, the format of the response of this API changes to return a list of [Search Results with Shared Links](r://search_results_with_shared_links) | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Starts workflow based on request body **Slug:** `BOX_START_WORKFLOW` Starts a Box Relay workflow with trigger type `WORKFLOW_MANUAL_START`. Prerequisites: - Your application must have the 'Manage Box Relay' scope enabled in the Box Developer Console. - Use the 'List Workflows' endpoint to get the workflow_id, flow.id, and folder.id. - All files specified must exist in the workflow's configured folder. Workflow: 1. Call 'List Workflows' with the folder_id to get available workflows. 2. From the response, extract: workflow.id, flows[].id, and any outcome IDs if needed. 3. Call this endpoint with the extracted IDs and the file IDs to process. Returns HTTP 204 No Content on success. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string ("workflow_parameters") | No | The type of the parameters object. Must be 'workflow_parameters'. | | `files` | array | Yes | Array of file objects to process with the workflow. Maximum 20 files per request. All files must be located in the workflow's configured folder. | | `flow__id` | string | No | The unique identifier of the flow to trigger. Obtain this from the workflow's 'flows' array in the List Workflows response. | | `outcomes` | array | No | Optional array of configurable outcomes for the workflow. Required if the workflow has runtime-configurable outcomes defined. | | `flow__type` | string | No | The type of the flow object. Must be 'flow'. | | `folder__id` | string | No | The unique identifier of the folder where the workflow is configured. This must match the folder associated with the workflow. | | `workflow_id` | string | Yes | The unique identifier of the workflow to start. Obtain this from the List Workflows endpoint. | | `folder__type` | string ("folder") | No | The type of the folder object. Must be 'folder'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create jobs to terminate user group session **Slug:** `BOX_TERMINATE_USER_GROUP_SESSIONS` Terminates all active sessions for users belonging to the specified Box enterprise groups. This action validates the roles and permissions of each group, then creates asynchronous background jobs to terminate sessions for all users in those groups. The operation is processed asynchronously - check admin events to monitor job status. Requires admin privileges. Use this to enforce security policies or respond to security incidents affecting entire groups. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `group_ids` | array | Yes | A list of Box enterprise group IDs whose members' sessions should be terminated. At least one group ID must be provided. Each group ID is a numeric string (e.g., '25521921228'). Use the list_groups_for_enterprise action to retrieve valid group IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Create jobs to terminate users session **Slug:** `BOX_TERMINATE_USER_SESSIONS` Creates asynchronous jobs to terminate active Box sessions for specified users. Use this when a user account may be compromised, a device is lost/stolen, or you need to force users to re-authenticate. This logs out users from all active sessions including web, desktop, and mobile apps. Both user_ids and user_logins parameters are required. Returns HTTP 202 on success with an async job created. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `user_ids` | array | Yes | A list of Box user IDs whose sessions should be terminated. Example: ['48351505451', '48351542393']. Both user_ids and user_logins are required. | | `user_logins` | array | Yes | A list of user login email addresses corresponding to the user_ids. Example: ['user@example.com', 'user2@example.com']. Both user_ids and user_logins are required. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Transfer owned folders **Slug:** `BOX_TRANSFER_OWNED_FOLDERS` Transfers all files and folders owned by one user to another user's account in Box. This creates a new folder in the destination user's root directory containing all the source user's content. The operation is commonly used for employee offboarding, role transitions, or account consolidation. Important: This operation is irreversible and requires enterprise admin permissions. All existing shared links and folder-level collaborations are preserved during transfer. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | List of field names to include in the response (e.g., ['id', 'name', 'owned_by']). When specified, only the requested fields plus mini representation fields are returned. If not specified, the standard folder object with all default fields is returned. | | `notify` | boolean | No | Determines if users should receive email notification for the action performed. | | `user_id` | string | Yes | The ID of the source user whose content will be transferred. All files and folders owned by this user will be moved to the destination user's account. Use BOX_LIST_ENTERPRISE_USERS to find valid user IDs. Requires enterprise admin permissions. | | `owned__by__id` | string | Yes | The ID of the destination user who will receive ownership of the transferred content. A new folder will be created in this user's root directory containing all the source user's files and folders. Use BOX_LIST_ENTERPRISE_USERS to find valid user IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Trim metadata taxonomy levels **Slug:** `BOX_TRIM_METADATA_TAXONOMY_LEVELS` Deletes the last level from a metadata taxonomy by trimming it. Use when you need to remove the deepest hierarchical level from a taxonomy structure. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `namespace` | string | Yes | The namespace of the metadata taxonomy. For enterprise taxonomies, this is typically in the format 'enterprise_123456' where 123456 is your enterprise ID. You can find this by listing metadata templates or inspecting existing metadata instances. | | `taxonomy_key` | string | Yes | The key of the metadata taxonomy to trim. This identifies the specific taxonomy whose last level will be removed. The taxonomy key is defined when the taxonomy is created and can be found by listing metadata templates. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Unassign legal hold policy **Slug:** `BOX_UNASSIGN_LEGAL_HOLD_POLICY` Remove a legal hold policy assignment from an item (user, folder, file, or file version). This endpoint unassigns a legal hold policy by deleting the assignment record. When successful, the API returns a 202 Accepted response with an empty body. IMPORTANT: This is an asynchronous operation - the legal hold is not fully removed when the response returns. The removal process continues in the background. To get the assignment ID: - Use 'assign_legal_hold_policy' and capture the returned 'id' field - Or use 'list_legal_hold_policy_assignments' to find existing assignment IDs Prerequisites: - Box Enterprise account with Box Governance add-on - OAuth scope: 'manage_legal_hold' - Admin-level permissions on the Box account Use case: Remove legal holds when litigation is resolved or content no longer needs to be preserved for compliance purposes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `legal_hold_policy_assignment_id` | string | Yes | The unique identifier of the legal hold policy assignment to remove. This ID can be obtained from 'assign_legal_hold_policy' (which returns it upon creation) or from 'list_legal_hold_policy_assignments'. Example: '753465' | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update AI Agent **Slug:** `BOX_UPDATE_AI_AGENT` Updates an existing custom AI agent in Box AI Studio. You can modify the agent's name, access settings, icon, and capability configurations (ask, text_gen, extract). **Requirements:** - Box Enterprise Advanced account with Box AI Studio enabled - "Manage AI" scope must be enabled in the Box Developer Console **Usage Notes:** - The `type` field must always be set to 'ai_agent' - Only custom agents (origin='CUSTOM') can be updated; Box default agents cannot be modified - When updating capabilities, provide all required fields (type, access_state, description) - Use `enabled_for_selected_users` access_state with `allowed_entities` to restrict access **Example:** To update an agent's name and enable the ask capability: agent_id="1234567890", name="Updated Agent", access_state="enabled", ask_type="ai_agent_ask", ask_access_state="enabled", ask_description="Ask questions about documents" #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | The display name of the AI Agent. This name will be visible to users in the Box interface. | | `type` | string ("ai_agent") | No | The type of agent. Must be 'ai_agent' for all AI agents. | | `agent_id` | string | Yes | The unique identifier of the AI Agent to update. This is a numeric string ID returned when creating an agent or listing agents. | | `ask__type` | string ("ai_agent_ask") | No | Type for the 'ask' capability. Must be 'ai_agent_ask' when configuring this capability. | | `access_state` | string | Yes | Controls who can access the AI Agent. Values: 'enabled' (all users), 'disabled' (no users), 'enabled_for_selected_users' (only users/groups in allowed_entities). | | `extract__type` | string ("ai_agent_extract") | No | Type for the 'extract' capability. Must be 'ai_agent_extract' when configuring this capability. | | `icon_reference` | string | No | URL to the agent's avatar icon. Must use format: https://cdn01.boxcdn.net/app-assets/aistudio/avatars/ Valid file names (supports both .png and .svg): logo_boxAi, logo_stamp, logo_legal, logo_finance, logo_config, logo_handshake, logo_analytics, logo_classification. Example: https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg | | `text__gen__type` | string ("ai_agent_text_gen") | No | Type for the 'text_gen' capability. Must be 'ai_agent_text_gen' when configuring this capability. | | `allowed_entities` | array | No | List of users or groups allowed to access the agent (only used when access_state is 'enabled_for_selected_users'). Each entity should have 'type' ('user' or 'group') and 'id' fields. | | `ask__description` | string | No | Description of the agent's 'ask' capability shown to users. Explains what questions the agent can answer. | | `ask__access__state` | string | No | Whether the 'ask' capability is active. Values: 'enabled' or 'disabled'. | | `extract__description` | string | No | Description of the agent's metadata extraction capability shown to users. Explains what data the agent can extract from documents. | | `extract__access__state` | string | No | Whether the 'extract' capability is active. Values: 'enabled' or 'disabled'. | | `text__gen__description` | string | No | Description of the agent's text generation capability shown to users. Explains what content the agent can create. | | `text__gen__access__state` | string | No | Whether the 'text_gen' capability is active. Values: 'enabled' or 'disabled'. | | `ask__custom__instructions` | string | No | Custom system instructions for the 'ask' capability. Used to define the agent's behavior, tone, and constraints when answering questions. | | `ask__suggested__questions` | array | No | List of suggested questions displayed to users for the 'ask' capability (max 4 items). Example: ['What is in this file?', 'Summarize the key points']. | | `extract__custom__instructions` | string | No | Custom system instructions for metadata extraction. Used to define extraction rules, field mappings, and output formatting. | | `text__gen__custom__instructions` | string | No | Custom system instructions for text generation. Used to define writing style, format preferences, and content guidelines. | | `text__gen__suggested__questions` | array | No | List of suggested prompts displayed to users for text generation (max 4 items). Example: ['Write a summary', 'Create a report']. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update all box skill cards on file **Slug:** `BOX_UPDATE_ALL_BOX_SKILL_CARDS_ON_FILE` An alternative method to overwrite and update all Box Skill metadata cards on a file. IMPORTANT: This endpoint is designed for Box Skills applications. The skill_id parameter must be a valid Box-assigned skill invocation ID that is received in the webhook payload when Box triggers a skill on a file. This ID is NOT a user-created identifier. Use Cases: - Update skill card metadata after processing a file with a custom Box Skill - Report processing status (success, failure, in-progress) back to Box - Overwrite existing skill cards with new results from ML/AI processing For creating skill cards on files without a skill invocation ID, use: - 'create_box_skill_cards_on_file' to add new skill cards - 'list_box_skill_cards_on_file' to view existing skill cards - 'remove_box_skill_cards_from_file' to delete skill cards #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `status` | string ("invoked" | "permanent_failure" | "processing" | "success" | "transient_failure") | Yes | Defines the status of this skill invocation. Set to 'success' when applying completed skill cards. Use 'processing' to indicate ongoing processing, 'invoked' when the skill has been triggered, 'transient_failure' for recoverable errors, or 'permanent_failure' for unrecoverable errors. | | `file__id` | string | No | The ID of the file to assign the skill cards to. Required when specifying file. The file ID can be found in the Box URL: https://*.app.box.com/files/{file_id} | | `skill_id` | string | Yes | The Box-assigned skill invocation ID. This ID is received in the webhook payload sent by Box when a skill is triggered on a file. It is NOT the same as the skill service ID or invocation ID you specify in skill cards. Example format: a numeric string like '33243242'. | | `file__type` | string ("file") | No | The type of the item, always 'file'. Required when specifying file. | | `usage__unit` | string | No | The unit of usage for the skill invocation, typically 'file'. This is usually omitted unless tracking skill usage metrics. | | `usage__value` | integer | No | The value of usage for the skill invocation, typically 1. This is usually omitted unless tracking skill usage metrics. | | `metadata__cards` | array | No | A list of Box Skill cards to apply to this file. These cards will overwrite any existing skill cards on the file. Each card must include: 'type' (always 'skill_card'), 'skill_card_type' (one of: 'keyword', 'transcript', 'timeline', 'status'), 'skill' (object with 'type': 'service' and 'id'), 'invocation' (object with 'type': 'skill_invocation' and 'id'), and 'skill_card_title' (object with 'code' and 'message'). Additional fields depend on card type. | | `file__version__id` | string | No | The ID of the specific file version to assign the cards to. Optional - if not provided, the cards are applied to the current file version. | | `file__version__type` | string ("file_version") | No | The type of the file version, always 'file_version'. Only required when targeting a specific file version instead of the current version. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update shield information barrier segment with specified id **Slug:** `BOX_UPDATE_BARRIER_SEGMENT` Updates a shield information barrier segment's name and/or description. Shield Information Barrier segments represent organizational divisions (e.g., 'Investment Banking', 'Research', 'Trading') that need to be isolated from each other for regulatory compliance or information security purposes. Use this action to modify a segment's identifying information after creation. At least one of 'name' or 'description' should be provided. Requirements: - Box Shield license is required to use this feature - The segment must exist (obtained from list_shield_information_barrier_segments) - Admin permissions are required to update segments Returns 404 if segment not found, 409 if name conflicts with an existing segment. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | The new name for the shield information barrier segment (e.g., 'Investment Banking', 'Research Division'). Must be unique within the barrier. Cannot be empty or whitespace-only. | | `description` | string | No | The new description for the shield information barrier segment explaining its purpose (e.g., 'Corporate division that handles M&A advisory services'). Can be set to null to clear the existing description. | | `shield_information_barrier_segment_id` | string | Yes | The unique identifier of the shield information barrier segment to update. Obtain this ID from list_shield_information_barrier_segments or create_shield_information_barrier_segment actions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update box skill cards on file **Slug:** `BOX_UPDATE_BOX_SKILL_CARDS_ON_FILE` Updates one or more Box Skills metadata cards on a file using JSON-Patch format. This action allows you to selectively update specific skill cards by their index position without affecting other cards. Use the 'replace' operation to modify existing cards at specified positions (e.g., /cards/0 for the first card). NOTE: This updates existing cards in place. To view existing cards first, use 'list_box_skill_cards_on_file'. To add new cards, use 'create_box_skill_cards_on_file'. To remove all cards, use 'remove_box_skill_cards_from_file'. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `operations` | array | Yes | A JSON-Patch array of operations to update Box Skill cards. Each operation should have 'op' set to 'replace', 'path' pointing to the card index (e.g., '/cards/0'), and 'value' containing the complete updated skill card object. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update collaboration **Slug:** `BOX_UPDATE_COLLABORATION` Updates a collaboration. Can be used to change the owner of an item, or to accept collaboration invites. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `role` | string ("co-owner" | "editor" | "owner" | "previewer" | "previewer uploader" | "uploader" | "viewer" | "viewer uploader") | Yes | The level of access granted. | | `status` | string ("accepted" | "pending" | "rejected") | No | Set the status of a `pending` collaboration invitation, effectively accepting, or rejecting the invite. | | `expires_at` | string | No | Update 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. Additionally, a collaboration can only be given an expiration if it was created after the **Automatically remove invited collaborator** setting was enabled. | | `can_view_path` | boolean | No | 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. | | `collaboration_id` | string | Yes | The ID of the collaboration | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update comment **Slug:** `BOX_UPDATE_COMMENT` Update the message of a comment. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | array | No | A comma-separated list of attributes to include in the response. Available fields include: id, type, is_reply_comment, message, tagged_message, created_by, created_at, modified_at, item. If not specified, a standard set of fields is returned. Specifying this parameter returns only the requested fields plus the mini representation fields. | | `message` | string | No | The new text content for the comment. This replaces the existing message. Supports plain text and Unicode characters including emojis. | | `comment_id` | string | Yes | The unique identifier of the comment to update. You can obtain this ID from the 'list_file_comments' action or from the response when creating a comment with 'create_comment'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update file **Slug:** `BOX_UPDATE_FILE` Updates a file. This can be used to rename or move a file, create a shared link, or lock a file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | An optional different name for the file. This can be used to rename the file. | | `tags` | array | No | The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item"s current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise. | | `fields` | array | No | 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. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `parent__id` | string | No | The ID of a folder to move the file to. This can be used to move a file to a different location. For example, to move a file to the root folder, set this to '0'. Note: When passing parameters as JSON, use 'parent__id' (with double underscores). | | `collections` | array | No | An array of collections to make this file a member of. Currently we only support the `favorites` collection. To get the ID for a collection, use the [List all collections][1] endpoint. Passing an empty array `[]` or `null` will remove the file from all collections. [1]: e://get-collections | | `description` | string | No | The description for a file. This can be seen in the right-hand sidebar panel when viewing a file in the Box web app. Additionally, this index is used in the search index of the file, allowing users to find the file by the content in the description. | | `lock__access` | string ("lock") | No | Set to 'lock' to create a lock on the file, preventing others from modifying it. To remove a lock, use an API call with lock set to null in the raw request. The only accepted value is 'lock'. Note: When passing parameters as JSON, use 'lock__access' (with double underscores). | | `disposition_at` | string | No | The retention expiration timestamp for the given file. This date cannot be shortened once set on a file. | | `lock__expires__at` | string | No | Defines the time at which the lock expires. Note: When passing parameters as JSON, use 'lock__expires__at' (with double underscores). | | `permissions__can__download` | string ("company" | "open") | No | Defines who is allowed to download this file. The possible values are either `open` for everyone or `company` for the other members of the user"s enterprise. This setting overrides the download permissions that are normally part of the `role` of a collaboration. When set to `company`, this essentially removes the download option for external users with `viewer` or `editor` a roles. Note: When passing parameters as JSON, use 'permissions__can__download' (with double underscores). | | `lock__is__download__prevented` | boolean | No | Defines if the file can be downloaded while it is locked. Note: When passing parameters as JSON, use 'lock__is__download__prevented' (with double underscores). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update file request **Slug:** `BOX_UPDATE_FILE_REQUEST` Updates a file request in Box. File requests allow external users to upload files to a specific folder without needing a Box account. Use this action to modify file request settings such as title, description, status, and form requirements. Common use cases: - Activate or deactivate a file request by changing its status - Update the title or description shown to uploaders - Set or change form requirements (email, description) - Set an expiration date for the file request Note: File request IDs can only be obtained from the Box web application URL. There is no API endpoint to list all file requests. To find a file_request_id, navigate to the file request in Box web UI and copy the ID from the URL (e.g., https://*.app.box.com/filerequest/123). #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `title` | string | No | The new title for the file request. This is displayed to uploaders on the file request form. If not provided, the existing title is retained. | | `status` | string ("active" | "inactive") | No | Status of the file request. | | `if_match` | string | No | The etag of the file request. Pass this to ensure the file request hasn't changed since you last retrieved it. If the etag doesn't match, the update will fail with a 412 Precondition Failed error. | | `expires_at` | string | No | The date after which the file request will no longer accept submissions (ISO 8601 format, e.g., '2024-12-31T23:59:59Z'). After this date, the status is automatically set to 'inactive'. If not provided, the existing expiration is retained. Set to null to remove expiration. | | `description` | string | No | The new description for the file request. This is displayed to uploaders on the file request form. If not provided, the existing description is retained. | | `file_request_id` | string | Yes | The unique identifier of the file request to update. This ID can be found in the Box web application URL when viewing a file request (e.g., for URL 'https://*.app.box.com/filerequest/123', the file_request_id is '123'). Note: File request IDs cannot be listed via API and must be obtained from the Box web interface. | | `is_email_required` | boolean | No | Whether uploaders must provide their email address when submitting files. When true, an email field is shown on the file request form. If not provided, the existing setting is retained. | | `is_description_required` | boolean | No | Whether uploaders must provide a description when submitting files. When true, a description field is shown on the file request form. If not provided, the existing setting is retained. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update folder **Slug:** `BOX_UPDATE_FOLDER` Updates a folder. This can be also be used to move the folder, create shared links, update collaborations, and more. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | The optional new name for this folder. | | `tags` | array | No | The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item"s current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise. | | `fields` | array | No | 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. | | `parent` | object | No | Request schema for moving a folder to a new parent folder. | | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `sync_state` | string ("synced" | "not_synced" | "partially_synced") | No | Specifies whether a folder should be synced to a user"s device or not. This is used by Box Sync (discontinued) and is not used by Box Drive. | | `collections` | array | No | An array of collections to make this folder a member of. Currently we only support the `favorites` collection. To get the ID for a collection, use the [List all collections][1] endpoint. Passing an empty array `[]` or `null` will remove the folder from all collections. [1]: e://get-collections | | `description` | string | No | The optional description of this folder | | `shared_link` | object | No | Request schema for creating/updating a shared link on the folder. | | `folder_upload_email` | object | No | Request schema for configuring folder upload email. | | `can_non_owners_invite` | boolean | No | Specifies if users who are not the owner of the folder can invite new collaborators to the folder. | | `can_non_owners_view_collaborators` | boolean | No | Restricts collaborators who are not the owner of this folder from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators. When setting this field to `false`, it is required to also set `can_non_owners_invite_collaborators` to `false` if it has not already been set. | | `is_collaboration_restricted_to_enterprise` | boolean | No | Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update group **Slug:** `BOX_UPDATE_GROUP` Updates a specific group. Only admins of this group or users with admin-level permissions will be able to use this API. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | The new name for the group. Must be unique within the enterprise. | | `fields` | array | No | 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. | | `group_id` | string | Yes | The ID of the group. | | `provenance` | string | No | 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. | | `description` | string | No | A human readable description of the group. | | `invitability_level` | string ("admins_and_members" | "admins_only" | "all_managed_users") | No | 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. | | `external_sync_identifier` | string | No | 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. | | `member_viewability_level` | string ("admins_and_members" | "admins_only" | "all_managed_users") | No | 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 | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update group membership **Slug:** `BOX_UPDATE_GROUP_MEMBERSHIP` Updates a user's group membership. Only admins of this group or users with admin-level permissions will be able to use this API. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `role` | string ("admin" | "member") | No | The role of the user in the group. Valid values are 'admin' (group administrator with configurable permissions) or 'member' (regular group member). | | `fields` | array | No | 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. | | `group_membership_id` | string | Yes | The ID of the group membership to update. You can obtain this ID from the 'add_user_to_group' action response or by listing group members with 'list_members_of_group'. | | `configurable_permissions` | object | No | Custom configuration for the permissions a group admin will receive. This option has no effect on members with a role of 'member'. Available permission keys: 'can_create_accounts', 'can_edit_accounts', 'can_instant_login', 'can_run_reports'. Setting these permissions overwrites the default access levels of an admin. Omitted permissions will be enabled by default. Example: {'can_create_accounts': false, 'can_run_reports': true}. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update legal hold policy **Slug:** `BOX_UPDATE_LEGAL_HOLD_POLICY` Update an existing legal hold policy in Box. This action allows you to modify the name, description, and release notes of an existing legal hold policy. Legal hold policies are used to preserve content for litigation or compliance purposes. At least one of the optional parameters (policy_name, description, or release_notes) should be provided. Note: This is a Box Governance feature that requires an enterprise account with legal hold capabilities enabled. The authenticated user must have admin-level permissions with the 'manage_legal_holds' scope. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `description` | string | No | A new description for the legal hold policy. Maximum 500 characters. | | `policy_name` | string | No | The new name for the legal hold policy. Maximum 254 characters. | | `release_notes` | string | No | Notes explaining why the policy was released or any relevant release information. Maximum 500 characters. | | `legal_hold_policy_id` | string | Yes | The unique identifier (ID) of the legal hold policy to update. You can obtain this ID from the response of BOX_CREATE_LEGAL_HOLD_POLICY or BOX_LIST_ALL_LEGAL_HOLD_POLICIES. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update metadata instance on file **Slug:** `BOX_UPDATE_METADATA_INSTANCE_ON_FILE` Updates a metadata instance on a file using JSON-Patch operations. The metadata template must already be applied to the file before it can be updated. Only values that match the template schema are accepted. The update is atomic - if any operation fails, no changes are applied. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string | Yes | The scope of the metadata template. Use 'global' for Box-provided templates available to all enterprises, or 'enterprise' for templates created within your enterprise. The 'enterprise' value will be automatically converted to the format 'enterprise_{enterprise_id}' if needed. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `operations` | array | Yes | A JSON-Patch array of operations to apply to the metadata instance. The update is atomic - if any operation fails, no changes are applied. Operations are executed in the order provided. | | `template_key` | string | Yes | The name (key) of the metadata template. For example, 'properties' for the standard Box properties template, or a custom template key for enterprise templates. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update metadata instance on folder **Slug:** `BOX_UPDATE_METADATA_INSTANCE_ON_FOLDER` Updates metadata on a folder using JSON-Patch operations (RFC 6902). The metadata template must already be applied to the folder. Only values matching the template schema are accepted (except global.properties which accepts any key-value pairs). All operations are applied atomically - if any fail, no changes are made. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string | Yes | The scope of the metadata template. Use 'global' for global templates (like 'properties') or 'enterprise' for enterprise-specific templates. For enterprise templates, you can use either 'enterprise' or the full format 'enterprise_{enterprise_id}'. | | `folder_id` | string | Yes | The unique identifier that represents a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `operations` | array | Yes | A list of JSON-Patch operations (RFC 6902) to apply to the metadata instance. The changes are applied atomically - if any operation fails, no changes are made. Common operations: use 'replace' to update existing fields, 'add' to create or overwrite fields, 'remove' to delete fields. | | `template_key` | string | Yes | The name of the metadata template (templateKey). For example: 'properties' for the global.properties template, or a custom template key. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update metadata taxonomy **Slug:** `BOX_UPDATE_METADATA_TAXONOMY` Tool to update an existing metadata taxonomy's display name. Use when you need to rename a taxonomy while keeping its structure and key intact. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `namespace` | string | Yes | The namespace of the metadata taxonomy to update. For enterprise taxonomies, this typically follows the format 'enterprise_{id}'. Example: 'enterprise_123456'. | | `displayName` | string | Yes | The new display name for the taxonomy. This is the human-readable name shown in the Box web app. | | `taxonomy_key` | string | Yes | The key of the metadata taxonomy to update. This is the unique identifier for the taxonomy within the namespace. Example: 'geography' or 'test_taxonomy'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update metadata taxonomy node **Slug:** `BOX_UPDATE_METADATA_TAXONOMY_NODE` Tool to update an existing metadata taxonomy node's display name. Use when you need to rename a taxonomy node in the Box metadata taxonomy hierarchy. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `node_id` | string | Yes | The identifier of the metadata taxonomy node to update. | | `namespace` | string | Yes | The namespace of the metadata taxonomy (e.g., 'enterprise_123456'). | | `displayName` | string | Yes | The new display name for the taxonomy node. | | `taxonomy_key` | string | Yes | The key of the metadata taxonomy. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update metadata template **Slug:** `BOX_UPDATE_METADATA_TEMPLATE` Updates a metadata template by applying JSON-Patch operations. The template must already exist. The update is applied atomically - if any error occurs during the application of operations, the metadata template will not be changed. Use this to modify template properties, add/edit/remove fields, or manage enum/multiSelect options. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `scope` | string | Yes | The scope of the metadata template. Use 'global' for global templates or 'enterprise' for enterprise-specific templates. For enterprise templates, you can also use the full scope format like 'enterprise_123456'. | | `operations` | array | Yes | A list of JSON-Patch operations to apply to the metadata template. The operations are applied atomically - if any operation fails, the entire update is rolled back. Each operation must specify an 'op' field and may include 'data', 'fieldKey', 'fieldKeys', 'enumOptionKey', 'enumOptionKeys', 'multiSelectOptionKey', or 'multiSelectOptionKeys' depending on the operation type. | | `template_key` | string | Yes | The name of the metadata template (templateKey). For example: 'properties' for the global.properties template, or a custom template key. This identifier is unique within the scope of the template. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update retention policy **Slug:** `BOX_UPDATE_RETENTION_POLICY` Updates an existing Box retention policy. Use this action to modify retention policy settings such as name, description, retention duration, disposition action, and notification settings. Requires Box Governance add-on and 'manage retention policies' scope. Note: Non-modifiable policies have limited update options (can only extend duration, add folders, retire policy, or change notification settings). #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `status` | string ("active" | "retired") | No | Status of the retention policy. | | `description` | string | No | A text description of the retention policy. Maximum 500 characters. Set to empty string to clear the existing description. | | `policy_name` | string | No | The new name for the retention policy. Must be unique within the enterprise. | | `retention_type` | string ("modifiable" | "non-modifiable") | No | Specifies whether the policy can be modified. | | `retention_length` | string | No | The retention duration in days as an integer (e.g., 30, 365) or the string 'indefinite' for indefinite policies. Non-modifiable policies can only have their duration extended, not shortened. | | `disposition_action` | string ("permanently_delete" | "remove_retention") | No | Action to take when the retention policy expires. | | `are_owners_notified` | boolean | No | Whether to notify owners and co-owners when retention is about to expire. Notifications are sent before the retention duration ends. | | `retention_policy_id` | string | Yes | The unique identifier of the retention policy to update. | | `can_owner_extend_retention` | boolean | No | Whether content owners can extend the retention period before it expires. When true, owners see an option to extend retention on their files. | | `custom_notification_recipients` | array | No | A list of additional users to notify when retention is about to expire. Each user should be specified with their 'id' field. Example: [{'id': '12345678'}] | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update shared link on file **Slug:** `BOX_UPDATE_SHARED_LINK_ON_FILE` Updates a shared link on a file. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | Explicitly request the `shared_link` fields to be returned for this item. Defaults to 'shared_link' to return the shared link details after update. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `shared__link__access` | string ("collaborators" | "company" | "open") | No | The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. | | `shared__link__password` | string | No | The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`. | | `shared__link__unshared__at` | string | No | The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. | | `shared__link__vanity__name` | string | No | Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. | | `shared__link__permissions__can__edit` | boolean | No | If the shared link allows for editing of files. This can only be set when `access` is set to `open` or `company`. This value can only be `true` if `can_download` is also `true`. | | `shared__link__permissions__can__preview` | boolean | No | If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. | | `shared__link__permissions__can__download` | boolean | No | If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update shared link on folder **Slug:** `BOX_UPDATE_SHARED_LINK_ON_FOLDER` Updates a shared link on a folder. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | Explicitly request the `shared_link` fields to be returned for this item. Defaults to 'shared_link' to include the updated shared link information in the response. | | `folder_id` | string | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `shared__link__access` | string ("collaborators" | "company" | "open") | No | The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. | | `shared__link__password` | string | No | The password required to access the shared link. Set the password to `null` to remove it. Passwords must now be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`. | | `shared__link__unshared__at` | string | No | The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. | | `shared__link__vanity__name` | string | No | Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. | | `shared__link__permissions__can__edit` | boolean | No | This value can only be `false` for items with a `type` of `folder`. | | `shared__link__permissions__can__preview` | boolean | No | If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. | | `shared__link__permissions__can__download` | boolean | No | If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update shared link on web link **Slug:** `BOX_UPDATE_SHARED_LINK_ON_WEB_LINK` Updates a shared link on a web link. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fields` | string | No | Comma-separated list of fields to include in the response. Use 'shared_link' to return the shared link information in the response. | | `web_link_id` | string | Yes | The ID of the web link. | | `shared__link__access` | string ("collaborators" | "company" | "open") | No | The level of access for the shared link. This can be restricted to anyone with the link (`open`), only people within the company (`company`) and only those who have been invited to the folder (`collaborators`). If not set, this field defaults to the access level specified by the enterprise admin. To create a shared link with this default setting pass the `shared_link` object with no `access` field, for example `{ "shared_link": {} }`. The `company` access level is only available to paid accounts. | | `shared__link__password` | string | No | The password required to access the shared link. Note: Password protection may not be supported for web links and could result in an error. If supported, passwords must be at least eight characters long and include a number, upper case letter, or a non-numeric or non-alphabetic character. A password can only be set when `access` is set to `open`. | | `shared__link__unshared__at` | string | No | The timestamp at which this shared link will expire. This field can only be set by users with paid accounts. The value must be greater than the current date and time. | | `shared__link__vanity__name` | string | No | Defines a custom vanity name to use in the shared link URL, for example `https://app.box.com/v/my-shared-link`. Custom URLs should not be used when sharing sensitive content as vanity URLs are a lot easier to guess than regular shared links. | | `shared__link__permissions__can__edit` | boolean | No | If the shared link allows for editing. This parameter is not applicable to web links and will be ignored. It can only be set for files. | | `shared__link__permissions__can__preview` | boolean | No | If the shared link allows for previewing of files. This value is always `true`. For shared links on folders this also applies to any items in the folder. | | `shared__link__permissions__can__download` | boolean | No | If the shared link allows for downloading of files. This can only be set when `access` is set to `open` or `company`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Change shield information barrier status **Slug:** `BOX_UPDATE_SHIELD_INFORMATION_BARRIER_STATUS` Change the status of a shield information barrier. Shield information barriers are ethical walls that prevent exchanges or communication between individuals/groups within the same enterprise to avoid conflicts of interest. This action allows you to: - Set status to 'pending': Transition a barrier from 'draft' status in preparation for enablement - Set status to 'disabled': Deactivate an enabled or pending barrier Note: Barriers cannot be directly enabled via this endpoint. The 'enabled' status is set automatically by Box after all required segments and restrictions are configured on a 'pending' barrier. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | string | Yes | The unique identifier of the shield information barrier to update. You can get this ID from BOX_LIST_SHIELD_INFORMATION_BARRIERS or BOX_CREATE_SHIELD_INFORMATION_BARRIER. | | `status` | string ("disabled" | "pending") | Yes | The desired status for the shield information barrier. Use 'pending' to prepare the barrier for enablement (transition from draft), or 'disabled' to deactivate an active barrier. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update slack integration mapping **Slug:** `BOX_UPDATE_SLACK_INTEGRATION_MAPPING` Updates an existing [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack). Use this to change which Box folder is mapped to a Slack channel, or to update configuration options like automatic access management. Requires Admin or Co-Admin role and the 'manage_enterprise_properties' scope. At least one of 'box_item' or 'options' must be provided. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `options` | object | No | Configuration options for the integration mapping. | | `box_item` | object | No | Box folder information for the integration mapping update. | | `integration_mapping_id` | string | Yes | The unique identifier of the Slack integration mapping to update. Obtain this ID from the 'list_slack_integration_mappings' action. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update storage policy assignment **Slug:** `BOX_UPDATE_STORAGE_POLICY_ASSIGNMENT` Updates a storage policy assignment for an enterprise or user. Storage policies control where data is stored geographically (data residency). Use this action to change which storage policy is assigned to a user or enterprise. This action requires Box Zones or similar enterprise feature to be enabled and admin-level permissions with 'manage_enterprise_properties' scope. Use 'list_storage_policies' to get available policies and 'list_storage_policy_assignments' to find existing assignment IDs. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `storage__policy__id` | string | Yes | The unique ID of the new storage policy to assign to the user or enterprise. Get available policies using the 'list_storage_policies' action. | | `storage__policy__type` | string ("storage_policy") | No | The type of policy to assign. Must be 'storage_policy'. This field is fixed and agents typically don't need to specify it. | | `storage_policy_assignment_id` | string | Yes | The unique identifier of the storage policy assignment to update. Obtain this ID from the 'list_storage_policy_assignments' action or from a previous 'assign_storage_policy' response. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update task **Slug:** `BOX_UPDATE_TASK` Updates a task. This can be used to update a task's configuration, or to update its completion state. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string ("complete" | "review") | No | The type of task action. Use 'review' for approval tasks that can be approved or rejected, or 'complete' for general tasks that can be marked as done. This parameter is optional when updating. | | `due_at` | string | No | The due date and time for the task in RFC3339 format (e.g., '2026-12-31T23:59:59+00:00'). Note: Updating this field may have API restrictions; if you encounter errors, try updating other fields separately. | | `message` | string | No | Optional message or instructions for the task assignee. Can be updated to provide additional context or modify existing instructions. | | `task_id` | string | Yes | The ID of the task. | | `completion_rule` | string ("all_assignees" | "any_assignee") | No | Completion rule for the task. Use 'all_assignees' (default) to require all assignees to complete the task, or 'any_assignee' to require only one assignee to complete it. Note: Updating this field may have API restrictions; if you encounter errors, try updating other fields separately. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update task assignment **Slug:** `BOX_UPDATE_TASK_ASSIGNMENT` Updates a task assignment to change its resolution state or add a message. This endpoint allows updating the state of a task assigned to a user. Use this to mark tasks as completed, approved, rejected, or incomplete, and optionally add a message explaining the decision. Important notes: - Only the assignee can typically update their own task assignment - For 'complete' action tasks: use 'completed' or 'incomplete' - For 'review' action tasks: use 'approved', 'rejected', or 'incomplete' - At least one of 'message' or 'resolution_state' should be provided #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `message` | string | No | An optional message from the assignee about the task. Use this to provide context, notes, or feedback when updating the assignment status. | | `resolution_state` | string ("approved" | "completed" | "incomplete" | "rejected") | No | The resolution state of the task assignment. Valid values depend on the task's action type: For 'complete' tasks: 'incomplete' or 'completed'. For 'review' tasks: 'incomplete', 'approved', or 'rejected'. Note: Only the assigned user can typically update their own task assignment. | | `task_assignment_id` | string | Yes | The unique identifier of the task assignment to update. Task assignment IDs can be obtained from the 'assign_task' action response or by listing task assignments via 'list_task_assignments'. Example: '86294599054'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update teams integration mapping **Slug:** `BOX_UPDATE_TEAMS_INTEGRATION_MAPPING` Updates a Microsoft Teams integration mapping that links a Box folder to a Teams channel. This endpoint allows you to change which Box folder is associated with a Microsoft Teams channel through the Box for Teams integration. After updating, any new files shared in the Teams channel will be stored in the newly mapped Box folder. **Requirements:** - Admin or Co-Admin role in the Box enterprise - The 'manage_enterprise_properties' scope - Box for Teams must be installed in the relevant Microsoft Teams workspace **Use Cases:** - Reorganize where Teams channel files are stored in Box - Move team collaboration content to a different department folder - Update mappings after folder restructuring For more information, see: https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `box_item` | object | No | Box folder to which the Teams channel should be mapped. | | `integration_mapping_id` | string | Yes | The unique identifier of the Teams integration mapping to update. This ID can be obtained from the 'list_teams_integration_mappings' action. Example: '12345678'. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update terms of service **Slug:** `BOX_UPDATE_TERMS_OF_SERVICE` Updates an existing terms of service for the enterprise. This action allows you to modify the status (enabled/disabled) and text content of an existing terms of service. When enabled, users will be prompted to accept the terms before accessing Box content. Note: This endpoint requires enterprise admin permissions with 'Edit settings for your company' enabled. The Terms of Service feature must also be enabled for the enterprise in the Box Admin Console. Use 'list_terms_of_services' to find the terms_of_service_id to update. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `text` | string | Yes | The terms of service text to display to users when they are prompted to accept. Can be empty only when status is 'disabled'. | | `status` | string ("enabled" | "disabled") | Yes | Whether to enable or disable this terms of service. Use 'enabled' to activate it so users must accept it, or 'disabled' to deactivate. | | `terms_of_service_id` | string | Yes | The unique identifier of the terms of service to update. Use 'list_terms_of_services' action to find available IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update terms of service status for existing user **Slug:** `BOX_UPDATE_TERMS_OF_SERVICE_STATUS_FOR_EXISTING_USER` Updates the acceptance status of a terms of service for a user who has previously accepted or rejected it. This action allows you to change whether a user has accepted or rejected a specific terms of service. Use this for users who already have a status record. For users who are encountering the terms of service for the first time, use create_terms_of_service_status_for_new_user instead. Prerequisites: - The Terms of Service feature must be enabled for the enterprise in the Box Admin Console - A terms of service user status record must already exist for the user (created via create_terms_of_service_status_for_new_user) - Requires admin permissions with 'manage enterprise properties' or 'manage users' scope Use list_terms_of_service_user_statuses to find existing status IDs for users. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `is_accepted` | boolean | Yes | Whether the user has accepted the terms of service. Set to true to record acceptance, false to record rejection. | | `terms_of_service_user_status_id` | string | Yes | The unique identifier of the terms of service user status record to update. Obtain this ID from list_terms_of_service_user_statuses action. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update user **Slug:** `BOX_UPDATE_USER` Updates a managed or app user in an enterprise. This endpoint is only available to users and applications with the right admin permissions. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | The name of the user | | `role` | string ("coadmin" | "user") | No | The user’s enterprise role | | `login` | string | No | The email address the user uses to log in Note: If the target user"s email is not confirmed, then the primary login address cannot be changed. | | `phone` | string | No | The user’s phone number | | `fields` | array | No | 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. | | `notify` | boolean | No | Whether the user should receive an email when they are rolled out of an enterprise | | `status` | string ("active" | "cannot_delete_edit" | "cannot_delete_edit_upload" | "inactive") | No | The user"s account status | | `address` | string | No | The user’s address | | `user_id` | string | Yes | The ID of the user. | | `language` | string | No | The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format. | | `timezone` | string | No | The user's timezone (e.g., 'America/Los_Angeles', 'America/New_York', 'Europe/London') | | `job_title` | string | No | The user’s job title | | `enterprise` | string | No | Set this to `null` to roll the user out of the enterprise and make them a free user | | `space_amount` | integer | No | The user’s total available space in bytes. Set this to `-1` to indicate unlimited storage. | | `tracking_codes` | array | No | Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used. | | `is_sync_enabled` | boolean | No | Whether the user can use Box Sync | | `external_app_user_id` | string | No | An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users. Note: In order to update this field, you need to request a token using the application that created the app user. | | `can_see_managed_users` | boolean | No | Whether the user can see other enterprise users in their contact list | | `is_password_reset_required` | boolean | No | Whether the user is required to reset their password | | `notification__email__email` | string | No | The email address to send the notifications to. | | `is_exempt_from_device_limits` | boolean | No | Whether to exempt the user from enterprise device limits | | `is_external_collab_restricted` | boolean | No | Whether the user is allowed to collaborate with users outside their enterprise | | `is_exempt_from_login_verification` | boolean | No | Whether the user must use two-factor authentication | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update webhook **Slug:** `BOX_UPDATE_WEBHOOK` Updates an existing webhook's configuration. Use this action to modify a webhook's target item (file or folder), notification URL, or event triggers. Only the fields provided in the request will be updated; omitted fields remain unchanged. Requirements: - The notification URL must use HTTPS on port 443 - The URL must respond with HTTP 200-299 within 30 seconds - Requires 'Manage Webhooks' scope enabled for the application Note: When changing the target, both target_id and target_type must be provided together. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `address` | string | No | The HTTPS URL that will receive webhook notifications. Must use port 443 and return HTTP 200-299 within 30 seconds. | | `triggers` | array | No | List of event triggers that will fire the webhook (e.g., FILE.UPLOADED, FOLDER.CREATED). See TriggersEnm0 enum for all available options. | | `target__id` | string | No | The ID of the file or folder to monitor for events. Use this to change the target item that triggers the webhook. | | `webhook_id` | string | Yes | The unique identifier of the webhook to update. This ID is returned when creating a webhook or can be obtained from the list webhooks endpoint. | | `target__type` | string ("file" | "folder") | No | The type of item to monitor: 'file' or 'folder'. Must be provided together with target_id when changing the target. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Update web link **Slug:** `BOX_UPDATE_WEB_LINK` Updates a web link object. This action allows you to modify an existing web link's properties including: - Changing the URL destination - Updating the name and description - Moving it to a different folder - Configuring shared link settings (access level, password, vanity URL, expiration) All fields except web_link_id are optional - only provide the fields you want to update. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `url` | string | No | The new URL that the web link points to. Must start with "http://" or "https://". Example: "https://www.example.com" | | `name` | string | No | A new name for the web link. If not provided, the name will default to the URL. Example: "My Favorite Website" | | `parent__id` | string | No | The ID of the parent folder to move this web link into. Use this to move the web link to a different folder. Example: "12345" for a specific folder or "0" for the root folder. | | `description` | string | No | A new description for the web link to provide additional context. Example: "This is a link to our company website" | | `web_link_id` | string | Yes | The ID of the web link to update. | | `shared__link__access` | string ("collaborators" | "company" | "open") | No | The level of access for the shared link. Options: "open" - Anyone with the link can access; "company" - Only people within your company can access (paid accounts only); "collaborators" - Only invited collaborators can access. If not set, defaults to your enterprise admin settings. | | `shared__link__password` | string | No | Password to protect the shared link. Must be at least 8 characters and include a number, uppercase letter, or special character. Set to null to remove an existing password. Can only be used when shared_link_access is "open". Example: "SecurePass123" | | `shared__link__unshared__at` | string | No | ISO 8601 timestamp when the shared link will automatically expire. Must be in the future. Requires a paid account. Example: "2026-12-31T23:59:59Z" | | `shared__link__vanity__name` | string | No | Custom vanity name for the shared link URL (e.g., https://app.box.com/v/my-custom-link). Must be at least 12 characters. Note: Vanity URLs are easier to guess, so avoid using them for sensitive content. Example: "my-shared-link" | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload file **Slug:** `BOX_UPLOAD_FILE` Uploads a small file to Box. For file sizes over 50MB we recommend using the Chunk Upload APIs. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file` | object | Yes | The file to upload. | | `fields` | array | No | List of field names to include in the response. When specified, only the requested fields plus mini representation fields (id, type, etag) are returned. Standard fields like created_at, modified_at, owned_by, modified_by, and item_status are omitted unless explicitly included in this list. Omit this parameter to receive the full standard response with all fields. | | `parent_id` | string | No | The ID of the parent folder to upload the file to. Use '0' for root folder. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload file version **Slug:** `BOX_UPLOAD_FILE_VERSION` Update a file's content. For file sizes over 50MB we recommend using the Chunk Upload APIs. The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file` | object | Yes | The file to upload as a new version. | | `fields` | array | No | 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. | | `file_id` | string | Yes | The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Upload part of file **Slug:** `BOX_UPLOAD_PART_OF_FILE` Uploads a chunk of a file for an upload session. The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints. Requirements: - Chunked uploads require files with a minimum size of 20MB - Each part's size must match the part_size from the upload session (except the last part) - The offset must be a multiple of the part_size - Parts cannot overlap with previously uploaded parts #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file` | object | Yes | The file chunk to upload. | | `offset` | integer | Yes | The byte offset of the chunk within the file. Must be a multiple of the part size from the upload session. | | `total_size` | integer | Yes | The total size of the file being uploaded in bytes. | | `upload_session_id` | string | Yes | The ID of the upload session. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ## Triggers ### Collaboration Details Changed **Slug:** `BOX_COLLABORATION_DETAILS_CHANGED_TRIGGER` **Type:** poll Triggers when a collaboration's details change (e.g., role, status, expiration). This trigger monitors a specific collaboration and detects when any meaningful field changes, such as role, status, expiration date, access type, or acknowledgment status. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `collaboration_id` | string | Yes | The unique identifier of the collaboration to monitor for changes. This is a numeric string ID returned when creating or listing collaborations (e.g., '69886391395'). | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `changed_fields` | array | No | List of field names that changed (e.g., 'role', 'status', 'expires_at') | | `collaboration` | object | Yes | The collaboration with updated details | | `current_values` | object | No | Current values of changed fields | | `event_type` | string | No | Type of event that occurred | | `previous_values` | object | No | Previous values of changed fields | ### Comment Changed **Slug:** `BOX_COMMENT_CHANGED_TRIGGER` **Type:** poll Triggers when a comment's content or details change in Box. This trigger monitors a specific Box comment and detects when any meaningful field changes, such as message text edits, tagged message changes, or modification timestamp updates. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `comment_id` | string | Yes | The unique identifier of the comment to monitor for changes. Comment IDs can be obtained from the 'list_file_comments' action or when creating a comment. Example: '12345678'. | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `changed_fields` | array | No | List of field names that changed (e.g., 'message', 'modified_at') | | `comment` | object | Yes | The comment with updated content | | `current_values` | object | No | Current values of changed fields | | `event_type` | string | No | Type of event that occurred | | `previous_values` | object | No | Previous values of changed fields | ### New File Comment Added **Slug:** `BOX_FILE_COMMENT_ADDED_TRIGGER` **Type:** poll Triggers when a new comment is added to a file in Box. This trigger monitors a specific Box file and fires when new comments are detected. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier of the file to monitor for new comments. File IDs can be obtained from file URLs or from actions like 'list_items_in_folder'. Example: '2090489102308'. | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | | `limit` | integer | No | Maximum number of comments to check in each poll (default: 100) | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `comment` | object | Yes | The newly added comment | | `event_type` | string | No | Type of event that occurred | ### File Metadata Changed **Slug:** `BOX_FILE_METADATA_CHANGED_TRIGGER` **Type:** poll Triggers when a file's metadata or properties change in Box. This trigger monitors a specific Box file and fires when changes are detected in key fields like name, description, size, modification time, parent folder, or status. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier of the file to monitor for metadata or property changes. File IDs can be obtained from the 'upload_file', 'list_items_in_folder', or 'search_for_content' actions. Example: '2119320206124'. | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `changed_fields` | array | No | List of field names that changed in this update | | `event_type` | string | No | Type of event that occurred | | `file` | object | Yes | The file with updated metadata | ### File Shared Link Changed **Slug:** `BOX_FILE_SHARED_LINK_CHANGED_TRIGGER` **Type:** poll Triggers when a file's shared link settings change in Box. This trigger monitors a specific Box file's shared link and fires when changes are detected in the shared link configuration, such as access level, permissions, password protection, expiration date, or vanity URL. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier of the file to monitor for shared link changes. File IDs can be obtained from the 'upload_file', 'list_items_in_folder', or 'search_for_content' actions. Example: '2090483963494'. | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `change_type` | string | Yes | Type of change: 'created', 'modified', or 'removed' | | `changed_fields` | array | No | List of shared link field names that changed | | `event_type` | string | No | Type of event that occurred | | `file_id` | string | Yes | The unique identifier of the file | | `file_name` | string | Yes | The name of the file | | `shared_link` | object | No | Shared link information for the file. | ### New File Version Uploaded **Slug:** `BOX_FILE_VERSION_UPLOADED_TRIGGER` **Type:** poll Triggers when a new file version is uploaded to a file in Box. This trigger monitors a specific Box file and fires when new versions are detected. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier of the file to monitor for new versions. The ID for any file can be determined by visiting this file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | | `limit` | integer | No | Maximum number of versions to check in each poll (1-1000) | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `event_type` | string | No | Type of event that occurred | | `file_id` | string | Yes | The ID of the file this version belongs to | | `file_version` | object | Yes | The newly uploaded file version | ### New Item Added to Folder **Slug:** `BOX_FOLDER_ITEM_ADDED_TRIGGER` **Type:** poll Triggers when a new item (file, folder, or web link) is added to a folder in Box. This trigger monitors a specific Box folder and fires when new items are detected. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier of the folder to monitor for new items. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | | `limit` | integer | No | Maximum number of items to check in each poll (1-1000) | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `event_type` | string | No | Type of event that occurred | | `item` | object | Yes | The newly added item | ### Folder Properties Changed **Slug:** `BOX_FOLDER_PROPERTIES_CHANGED_TRIGGER` **Type:** poll Triggers when a folder's core properties change in Box. This trigger monitors a specific Box folder and fires when changes are detected in properties like name, description, modification time, parent folder, item status, or shared link settings. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier of the folder to monitor for property changes. Folder IDs can be obtained from actions like 'create_folder', 'list_items_in_folder', or 'search_for_content'. The root folder is always represented by ID '0'. Example: '353353898191'. | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `changed_fields` | array | No | List of property field names that changed. | | `description` | string | No | Current folder description. | | `event_type` | string | No | Type of event that occurred. | | `folder_id` | string | Yes | The unique identifier of the folder. | | `folder_name` | string | Yes | The current name of the folder. | | `item_status` | string | No | Current item status: 'active', 'trashed', or 'deleted'. | | `modified_at` | string | No | Last modification timestamp. | | `name` | string | No | Current folder name. | | `parent` | object | No | Schema for folder mini representation. | | `shared_link` | object | No | Shared link information for the folder. | ### Folder Shared Link Changed **Slug:** `BOX_FOLDER_SHARED_LINK_CHANGED_TRIGGER` **Type:** poll Triggers when a folder's shared link settings change in Box. This trigger monitors a specific Box folder's shared link and fires when changes are detected in the shared link configuration, such as access level, permissions, password protection, expiration date, or vanity URL. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier of the folder to monitor for shared link changes. Folder IDs can be obtained from the 'create_folder', 'list_items_in_folder', or 'search_for_content' actions. The root folder is always represented by ID '0'. Example: '353353898191'. | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `change_type` | string | Yes | Type of change: 'created', 'modified', or 'removed' | | `changed_fields` | array | No | List of shared link field names that changed | | `event_type` | string | No | Type of event that occurred | | `folder_id` | string | Yes | The unique identifier of the folder | | `folder_name` | string | Yes | The name of the folder | | `shared_link` | object | No | Shared link information for the folder. | ### New File Added to Folder **Slug:** `BOX_NEW_FILE_ADDED_TRIGGER` **Type:** poll Triggers when a new file is added to a folder in Box. This trigger monitors a specific Box folder and fires when new files are detected. Only files (not folders or web links) are monitored. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier of the folder to monitor for new files. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | | `limit` | integer | No | Maximum number of items to check in each poll (1-1000) | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `event_type` | string | No | Type of event that occurred | | `file` | object | Yes | The newly added file | ### New Folder Collaboration Created **Slug:** `BOX_NEW_FOLDER_COLLABORATION_CREATED_TRIGGER` **Type:** poll Triggers when a new collaboration is created on a specific folder in Box. This trigger monitors a specific Box folder and fires when new collaborations are detected. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier of the folder to monitor for collaborations. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | | `limit` | integer | No | Maximum number of collaborations to check in each poll (1-1000) | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `collaboration` | object | Yes | The newly created folder collaboration | | `event_type` | string | No | Type of event that occurred | ### New Pending Collaboration Invite **Slug:** `BOX_NEW_PENDING_COLLABORATION_TRIGGER` **Type:** poll Triggers when a new pending collaboration invite is created. This trigger monitors the user's pending collaborations and fires when new pending collaboration invites are detected. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | | `limit` | integer | No | Maximum number of pending collaborations to check in each poll (1-1000) | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `collaboration` | object | Yes | The new pending collaboration invite | | `event_type` | string | No | Type of event that occurred | ### New Sign Request Created **Slug:** `BOX_NEW_SIGN_REQUEST_CREATED_TRIGGER` **Type:** poll Triggers when a new Box sign request is created. This trigger monitors Box sign requests and fires when new sign requests are detected. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | | `limit` | integer | No | Maximum number of sign requests to check in each poll (1-1000) | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `event_type` | string | No | Type of event that occurred | | `sign_request` | object | Yes | The newly created Box sign request | ### New Task Assignment Added **Slug:** `BOX_NEW_TASK_ASSIGNMENT_TRIGGER` **Type:** poll Triggers when a new assignment is added to a task in Box. This trigger monitors a specific Box task and fires when new assignments are detected. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | | `task_id` | string | Yes | The unique identifier of the task to monitor for new assignments. Task IDs can be obtained from the 'create_task' or 'list_tasks_on_file' actions. Example: '39641675308'. | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `event_type` | string | No | Type of event that occurred | | `task_assignment` | object | Yes | The newly added task assignment | ### New Task Created on File **Slug:** `BOX_NEW_TASK_CREATED_TRIGGER` **Type:** poll Triggers when a new task is created on a Box file. This trigger monitors a specific Box file and fires when new tasks are detected. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier of the file to monitor for new tasks. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `event_type` | string | No | Type of event that occurred | | `task` | object | Yes | The newly created task on the file | ### Box Sign Request Status Changed **Slug:** `BOX_SIGN_REQUEST_STATUS_CHANGED_TRIGGER` **Type:** poll Triggers when a Box Sign request's status or meaningful fields change. This trigger monitors a specific Box Sign request and fires when changes are detected in key fields like status, signer decisions, document readiness, or completion state. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | | `sign_request_id` | string | Yes | The unique identifier (UUID) of the Box Sign request to monitor for status or detail changes. This ID can be obtained from the response when creating a sign request or by listing all sign requests. Example: 'c5c832e7-b890-4a48-96f5-27ce66d1e3b9'. | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `changed_fields` | array | No | List of field names that changed in this update | | `event_type` | string | No | Type of event that occurred | | `sign_request` | object | Yes | The Box Sign request with updated state | ### Task Assignment State Changed **Slug:** `BOX_TASK_ASSIGNMENT_STATE_CHANGED_TRIGGER` **Type:** poll Triggers when a task assignment's state changes. This trigger monitors task assignments for a specific task and detects when the resolution_state changes (e.g., from incomplete to completed, or from completed to approved/rejected). #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | | `task_id` | string | Yes | The unique identifier of the task to monitor for assignment state changes. Task IDs can be obtained from the 'create_task' or 'list_tasks_on_file' actions. | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `assignment` | object | Yes | The task assignment with updated state | | `current_state` | string | No | The current resolution state of the assignment | | `event_type` | string | No | Type of event that occurred | | `previous_state` | string | No | The previous resolution state of the assignment | ### Task State Changed **Slug:** `BOX_TASK_STATE_CHANGED_TRIGGER` **Type:** poll Triggers when a task's status or details change in Box. This trigger monitors a specific Box task and fires when changes are detected in key fields like status, due date, message, or completion state. #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | | `task_id` | string | Yes | The unique identifier of the task to monitor for status or detail changes. Task IDs can be obtained from the 'create_task' or 'list_tasks_on_file' actions. Example: '39641675308'. | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `changed_fields` | array | No | List of field names that changed in this update | | `event_type` | string | No | Type of event that occurred | | `task` | object | Yes | The task with updated state | ### Trashed File State Changed **Slug:** `BOX_TRASHED_FILE_STATE_CHANGED_TRIGGER` **Type:** poll Triggers when a file's trash state changes in Box. This trigger monitors a specific Box file and fires when its trash state changes (e.g., moved to trash or restored from trash). #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file_id` | string | Yes | The unique identifier of the file to monitor for trash state changes. The file ID can be obtained from the 'get_file_information' or 'list_items_in_folder' actions. Example: '2119317417511'. | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `changed_fields` | array | No | List of field names that changed in this update | | `current_state` | string | No | Current item_status value ('active', 'trashed', or 'deleted') | | `event_type` | string | No | Type of event that occurred | | `file` | object | Yes | The file with updated trash state | | `previous_state` | string | No | Previous item_status value ('active', 'trashed', or 'deleted') | ### Trashed Folder State Changed **Slug:** `BOX_TRASHED_FOLDER_STATE_CHANGED_TRIGGER` **Type:** poll Triggers when a folder's trash state changes in Box. This trigger monitors a specific Box folder and fires when its trash state changes (e.g., moved to trash or restored from trash). #### Configuration | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `folder_id` | string | Yes | The unique identifier of the folder to monitor for trash state changes. The folder ID can be obtained from the 'get_folder_information' or 'list_items_in_folder' actions. Example: '353353898191'. | | `interval` | number | No | Periodic Interval to Check for Updates & Send a Trigger in Minutes | #### Payload | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `changed_fields` | array | No | List of field names that changed in this update | | `current_state` | string | No | Current item_status value ('active', 'trashed', or 'deleted') | | `event_type` | string | No | Type of event that occurred | | `folder` | object | Yes | The folder with updated trash state | | `previous_state` | string | No | Previous item_status value ('active', 'trashed', or 'deleted') |