# Box (/integrations/box)





{/* MANUAL-CONTENT-START:intro */}

Use [Box](https://www.box.com/) to manage files and folders, search content, and send documents for e-signature through Box Sign. The actions below cover file metadata and signing status as well as uploads and downloads.

{/* MANUAL-CONTENT-END */}

Connection guides: [Service accounts](/integrations/box-service-account).

## OAuth scopes [#oauth-scopes]

Sim requests these scopes when someone connects a Box account. For a self-hosted deployment, register your own app with the provider using the settings below. See [Integrations and OAuth](/platform/self-hosting/integrations-oauth) for setup.

| Setting | Value |
| - | - |
| Redirect URI | `<NEXT_PUBLIC_APP_URL>/api/auth/oauth2/callback/box` |
| Environment variables | `BOX_CLIENT_ID`, `BOX_CLIENT_SECRET` |

| Scope | Description |
| - | - |
| `root_readwrite` | Read and write all files and folders in Box account |
| `sign_requests.readwrite` | Create and manage Box Sign e-signature requests |

## Use the block [#usage-instructions]

Manage files, folders, and e-signatures. Upload and download files, search content, create folders, send documents for e-signature, track signing status, and more.

## Actions [#actions]

### Box Upload File [#box-upload-file]

Upload a file to a Box folder

<ReferenceDetails>
  #### Input [#input]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `parentFolderId` | string | Yes | The ID of the folder to upload the file to (use "0" for root) |
  | `file` | file | No | The file to upload (UserFile object) |
  | `fileName` | string | No | Optional filename override |

  #### Output [#output]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | File ID |
  | `name` | string | File name |
  | `size` | number | File size in bytes |
  | `sha1` | string | SHA1 hash of file content |
  | `createdAt` | string | Creation timestamp |
  | `modifiedAt` | string | Last modified timestamp |
  | `parentId` | string | Parent folder ID |
  | `parentName` | string | Parent folder name |
</ReferenceDetails>

### Box Download File [#box-download-file]

Download a file from Box

<ReferenceDetails>
  #### Input [#input-1]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `fileId` | string | Yes | The ID of the file to download |

  #### Output [#output-1]

  | Parameter | Type | Description |
  | - | - | - |
  | `file` | file | Downloaded file stored in execution files |
</ReferenceDetails>

### Box Get File Info [#box-get-file-info]

Get detailed information about a file in Box

<ReferenceDetails>
  #### Input [#input-2]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `fileId` | string | Yes | The ID of the file to get information about |

  #### Output [#output-2]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | File ID |
  | `name` | string | File name |
  | `description` | string | File description |
  | `size` | number | File size in bytes |
  | `sha1` | string | SHA1 hash of file content |
  | `createdAt` | string | Creation timestamp |
  | `modifiedAt` | string | Last modified timestamp |
  | `createdBy` | object | User who created the file |
  | ↳ `id` | string | User ID |
  | ↳ `name` | string | User name |
  | ↳ `login` | string | User email/login |
  | `modifiedBy` | object | User who last modified the file |
  | ↳ `id` | string | User ID |
  | ↳ `name` | string | User name |
  | ↳ `login` | string | User email/login |
  | `ownedBy` | object | User who owns the file |
  | ↳ `id` | string | User ID |
  | ↳ `name` | string | User name |
  | ↳ `login` | string | User email/login |
  | `parentId` | string | Parent folder ID |
  | `parentName` | string | Parent folder name |
  | `sharedLink` | json | Shared link details |
  | `tags` | array | File tags |
  | `commentCount` | number | Number of comments |
</ReferenceDetails>

### Box List Folder Items [#box-list-folder-items]

List files and folders in a Box folder

<ReferenceDetails>
  #### Input [#input-3]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `folderId` | string | Yes | The ID of the folder to list items from (use "0" for root) |
  | `limit` | number | No | Maximum number of items to return per page |
  | `offset` | number | No | The offset for pagination |
  | `sort` | string | No | Sort field: id, name, date, or size |
  | `direction` | string | No | Sort direction: ASC or DESC |

  #### Output [#output-3]

  | Parameter | Type | Description |
  | - | - | - |
  | `entries` | array | List of items in the folder |
  | ↳ `type` | string | Item type (file, folder, web\_link) |
  | ↳ `id` | string | Item ID |
  | ↳ `name` | string | Item name |
  | ↳ `size` | number | Item size in bytes |
  | ↳ `createdAt` | string | Creation timestamp |
  | ↳ `modifiedAt` | string | Last modified timestamp |
  | `totalCount` | number | Total number of items in the folder |
  | `offset` | number | Current pagination offset |
  | `limit` | number | Current pagination limit |
</ReferenceDetails>

### Box Create Folder [#box-create-folder]

Create a new folder in Box

<ReferenceDetails>
  #### Input [#input-4]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `name` | string | Yes | Name for the new folder |
  | `parentFolderId` | string | Yes | The ID of the parent folder (use "0" for root) |

  #### Output [#output-4]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | Folder ID |
  | `name` | string | Folder name |
  | `createdAt` | string | Creation timestamp |
  | `modifiedAt` | string | Last modified timestamp |
  | `parentId` | string | Parent folder ID |
  | `parentName` | string | Parent folder name |
</ReferenceDetails>

### Box Delete File [#box-delete-file]

Delete a file from Box

<ReferenceDetails>
  #### Input [#input-5]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `fileId` | string | Yes | The ID of the file to delete |

  #### Output [#output-5]

  | Parameter | Type | Description |
  | - | - | - |
  | `deleted` | boolean | Whether the file was successfully deleted |
  | `message` | string | Success confirmation message |
</ReferenceDetails>

### Box Delete Folder [#box-delete-folder]

Delete a folder from Box

<ReferenceDetails>
  #### Input [#input-6]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `folderId` | string | Yes | The ID of the folder to delete |
  | `recursive` | boolean | No | Delete folder and all its contents recursively |

  #### Output [#output-6]

  | Parameter | Type | Description |
  | - | - | - |
  | `deleted` | boolean | Whether the folder was successfully deleted |
  | `message` | string | Success confirmation message |
</ReferenceDetails>

### Box Copy File [#box-copy-file]

Copy a file to another folder in Box

<ReferenceDetails>
  #### Input [#input-7]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `fileId` | string | Yes | The ID of the file to copy |
  | `parentFolderId` | string | Yes | The ID of the destination folder |
  | `name` | string | No | Optional new name for the copied file |

  #### Output [#output-7]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | File ID |
  | `name` | string | File name |
  | `size` | number | File size in bytes |
  | `sha1` | string | SHA1 hash of file content |
  | `createdAt` | string | Creation timestamp |
  | `modifiedAt` | string | Last modified timestamp |
  | `parentId` | string | Parent folder ID |
  | `parentName` | string | Parent folder name |
</ReferenceDetails>

### Box Search [#box-search]

Search for files and folders in Box

<ReferenceDetails>
  #### Input [#input-8]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `query` | string | Yes | The search query string |
  | `limit` | number | No | Maximum number of results to return |
  | `offset` | number | No | The offset for pagination |
  | `ancestorFolderId` | string | No | Restrict search to a specific folder and its subfolders |
  | `fileExtensions` | string | No | Comma-separated file extensions to filter by (e.g., pdf,docx) |
  | `type` | string | No | Restrict to a specific content type: file, folder, or web\_link |

  #### Output [#output-8]

  | Parameter | Type | Description |
  | - | - | - |
  | `results` | array | Search results |
  | ↳ `type` | string | Item type (file, folder, web\_link) |
  | ↳ `id` | string | Item ID |
  | ↳ `name` | string | Item name |
  | ↳ `size` | number | Item size in bytes |
  | ↳ `createdAt` | string | Creation timestamp |
  | ↳ `modifiedAt` | string | Last modified timestamp |
  | ↳ `parentId` | string | Parent folder ID |
  | ↳ `parentName` | string | Parent folder name |
  | `totalCount` | number | Total number of matching results |
</ReferenceDetails>

### Box Update File [#box-update-file]

Update file info in Box (rename, move, change description, add tags)

<ReferenceDetails>
  #### Input [#input-9]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `fileId` | string | Yes | The ID of the file to update |
  | `name` | string | No | New name for the file |
  | `description` | string | No | New description for the file (max 256 characters) |
  | `parentFolderId` | string | No | Move the file to a different folder by specifying the folder ID |
  | `tags` | string | No | Comma-separated tags to set on the file |

  #### Output [#output-9]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | File ID |
  | `name` | string | File name |
  | `description` | string | File description |
  | `size` | number | File size in bytes |
  | `sha1` | string | SHA1 hash of file content |
  | `createdAt` | string | Creation timestamp |
  | `modifiedAt` | string | Last modified timestamp |
  | `createdBy` | object | User who created the file |
  | ↳ `id` | string | User ID |
  | ↳ `name` | string | User name |
  | ↳ `login` | string | User email/login |
  | `modifiedBy` | object | User who last modified the file |
  | ↳ `id` | string | User ID |
  | ↳ `name` | string | User name |
  | ↳ `login` | string | User email/login |
  | `ownedBy` | object | User who owns the file |
  | ↳ `id` | string | User ID |
  | ↳ `name` | string | User name |
  | ↳ `login` | string | User email/login |
  | `parentId` | string | Parent folder ID |
  | `parentName` | string | Parent folder name |
  | `sharedLink` | json | Shared link details |
  | `tags` | array | File tags |
  | `commentCount` | number | Number of comments |
</ReferenceDetails>

### Box Sign Create Request [#box-sign-create-request]

Create a new Box Sign request to send documents for e-signature

<ReferenceDetails>
  #### Input [#input-10]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `sourceFileIds` | string | Yes | Comma-separated Box file IDs to send for signing |
  | `signerEmail` | string | Yes | Primary signer email address |
  | `signerRole` | string | No | Primary signer role: signer, approver, or final\_copy\_reader (default: signer) |
  | `additionalSigners` | string | No | JSON array of additional signers, e.g. \[\{"email":"[user@example.com](mailto:user@example.com)","role":"signer"}] |
  | `parentFolderId` | string | No | Box folder ID where signed documents will be stored (default: user root) |
  | `emailSubject` | string | No | Custom subject line for the signing email |
  | `emailMessage` | string | No | Custom message in the signing email body |
  | `name` | string | No | Name for the sign request |
  | `daysValid` | number | No | Number of days before the request expires (0-730) |
  | `areRemindersEnabled` | boolean | No | Whether to send automatic signing reminders |
  | `areTextSignaturesEnabled` | boolean | No | Whether to allow typed (text) signatures |
  | `signatureColor` | string | No | Signature color: blue, black, or red |
  | `redirectUrl` | string | No | URL to redirect signers to after signing |
  | `declinedRedirectUrl` | string | No | URL to redirect signers to after declining |
  | `isDocumentPreparationNeeded` | boolean | No | Whether document preparation is needed before sending |
  | `externalId` | string | No | External system reference ID |

  #### Output [#output-10]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | Sign request ID |
  | `status` | string | Request status (converting, created, sent, viewed, signed, cancelled, declined, expired, error\_converting, error\_sending, finalizing, error\_finalizing) |
  | `name` | string | Sign request name |
  | `shortId` | string | Human-readable short ID |
  | `signers` | array | List of signers |
  | ↳ `email` | string | Signer email address |
  | ↳ `role` | string | Signer role (signer, approver, final\_copy\_reader) |
  | ↳ `hasViewedDocument` | boolean | Whether the signer has viewed the document |
  | ↳ `signerDecision` | json | Signer decision details (type, finalized\_at, additional\_info) |
  | ↳ `embedUrl` | string | URL for embedded signing experience |
  | ↳ `order` | number | Order in signing sequence |
  | `sourceFiles` | array | Source files for signing |
  | ↳ `id` | string | File ID |
  | ↳ `type` | string | File type |
  | ↳ `name` | string | File name |
  | `emailSubject` | string | Custom email subject line |
  | `emailMessage` | string | Custom email message body |
  | `daysValid` | number | Number of days the request is valid |
  | `createdAt` | string | Creation timestamp |
  | `autoExpireAt` | string | Auto-expiration timestamp |
  | `prepareUrl` | string | URL for document preparation (if preparation is needed) |
  | `senderEmail` | string | Email of the sender |
</ReferenceDetails>

### Box Sign Get Request [#box-sign-get-request]

Get the details and status of a Box Sign request

<ReferenceDetails>
  #### Input [#input-11]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `signRequestId` | string | Yes | The ID of the sign request to retrieve |

  #### Output [#output-11]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | Sign request ID |
  | `status` | string | Request status (converting, created, sent, viewed, signed, cancelled, declined, expired, error\_converting, error\_sending, finalizing, error\_finalizing) |
  | `name` | string | Sign request name |
  | `shortId` | string | Human-readable short ID |
  | `signers` | array | List of signers |
  | ↳ `email` | string | Signer email address |
  | ↳ `role` | string | Signer role (signer, approver, final\_copy\_reader) |
  | ↳ `hasViewedDocument` | boolean | Whether the signer has viewed the document |
  | ↳ `signerDecision` | json | Signer decision details (type, finalized\_at, additional\_info) |
  | ↳ `embedUrl` | string | URL for embedded signing experience |
  | ↳ `order` | number | Order in signing sequence |
  | `sourceFiles` | array | Source files for signing |
  | ↳ `id` | string | File ID |
  | ↳ `type` | string | File type |
  | ↳ `name` | string | File name |
  | `emailSubject` | string | Custom email subject line |
  | `emailMessage` | string | Custom email message body |
  | `daysValid` | number | Number of days the request is valid |
  | `createdAt` | string | Creation timestamp |
  | `autoExpireAt` | string | Auto-expiration timestamp |
  | `prepareUrl` | string | URL for document preparation (if preparation is needed) |
  | `senderEmail` | string | Email of the sender |
</ReferenceDetails>

### Box Sign List Requests [#box-sign-list-requests]

List all Box Sign requests

<ReferenceDetails>
  #### Input [#input-12]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `limit` | number | No | Maximum number of sign requests to return (max 1000) |
  | `marker` | string | No | Pagination marker from a previous response |

  #### Output [#output-12]

  | Parameter | Type | Description |
  | - | - | - |
  | `signRequests` | array | List of sign requests |
  | ↳ `id` | string | Sign request ID |
  | ↳ `status` | string | Request status (converting, created, sent, viewed, signed, cancelled, declined, expired, error\_converting, error\_sending, finalizing, error\_finalizing) |
  | ↳ `name` | string | Sign request name |
  | ↳ `shortId` | string | Human-readable short ID |
  | ↳ `signers` | array | List of signers |
  | ↳ `email` | string | Signer email address |
  | ↳ `role` | string | Signer role (signer, approver, final\_copy\_reader) |
  | ↳ `hasViewedDocument` | boolean | Whether the signer has viewed the document |
  | ↳ `signerDecision` | json | Signer decision details (type, finalized\_at, additional\_info) |
  | ↳ `embedUrl` | string | URL for embedded signing experience |
  | ↳ `order` | number | Order in signing sequence |
  | ↳ `sourceFiles` | array | Source files for signing |
  | ↳ `id` | string | File ID |
  | ↳ `type` | string | File type |
  | ↳ `name` | string | File name |
  | ↳ `emailSubject` | string | Custom email subject line |
  | ↳ `emailMessage` | string | Custom email message body |
  | ↳ `daysValid` | number | Number of days the request is valid |
  | ↳ `createdAt` | string | Creation timestamp |
  | ↳ `autoExpireAt` | string | Auto-expiration timestamp |
  | ↳ `prepareUrl` | string | URL for document preparation (if preparation is needed) |
  | ↳ `senderEmail` | string | Email of the sender |
  | `count` | number | Number of sign requests returned in this page |
  | `nextMarker` | string | Marker for next page of results |
</ReferenceDetails>

### Box Sign Cancel Request [#box-sign-cancel-request]

Cancel a pending Box Sign request

<ReferenceDetails>
  #### Input [#input-13]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `signRequestId` | string | Yes | The ID of the sign request to cancel |

  #### Output [#output-13]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | Sign request ID |
  | `status` | string | Request status (converting, created, sent, viewed, signed, cancelled, declined, expired, error\_converting, error\_sending, finalizing, error\_finalizing) |
  | `name` | string | Sign request name |
  | `shortId` | string | Human-readable short ID |
  | `signers` | array | List of signers |
  | ↳ `email` | string | Signer email address |
  | ↳ `role` | string | Signer role (signer, approver, final\_copy\_reader) |
  | ↳ `hasViewedDocument` | boolean | Whether the signer has viewed the document |
  | ↳ `signerDecision` | json | Signer decision details (type, finalized\_at, additional\_info) |
  | ↳ `embedUrl` | string | URL for embedded signing experience |
  | ↳ `order` | number | Order in signing sequence |
  | `sourceFiles` | array | Source files for signing |
  | ↳ `id` | string | File ID |
  | ↳ `type` | string | File type |
  | ↳ `name` | string | File name |
  | `emailSubject` | string | Custom email subject line |
  | `emailMessage` | string | Custom email message body |
  | `daysValid` | number | Number of days the request is valid |
  | `createdAt` | string | Creation timestamp |
  | `autoExpireAt` | string | Auto-expiration timestamp |
  | `prepareUrl` | string | URL for document preparation (if preparation is needed) |
  | `senderEmail` | string | Email of the sender |
</ReferenceDetails>

### Box Sign Resend Request [#box-sign-resend-request]

Resend a Box Sign request to signers who have not yet signed

<ReferenceDetails>
  #### Input [#input-14]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `signRequestId` | string | Yes | The ID of the sign request to resend |

  #### Output [#output-14]

  | Parameter | Type | Description |
  | - | - | - |
  | `message` | string | Success confirmation message |
</ReferenceDetails>