Skip to main content

Box

Export reports to a Box folder as CSV, JSON Lines, or Parquet. Box supports Append delivery: each run creates a file. Extract never replaces an existing report or uploads a new version of it.

Prerequisites​

  • A Box folder where the authenticated user or app service account can read content, create subfolders, and upload files.
  • For OAuth, permission to authorize Extract's Box application. Your organization's administrator may need to enable it.
  • For server-to-server authentication, an authorized Box application using Client Credentials Grant (CCG). Developer tokens and JWT key pairs are not supported by this destination.

Box account entitlements, file-size limits, and administrator policies apply. A Starter account may not expose the Platform Apps Manager needed to authorize a server app. Check your account's developer capabilities before configuring CCG.

Connect with OAuth​

  1. Add Box from Destinations and select Sign in with Box.
  2. Click Connect with Box, sign into the Box account that can access your folder, and grant access.
  3. Enter the Root Folder ID, then save the destination.

The root folder ID is the number in its Box URL. For example, https://app.box.com/folder/123456789 has the ID 123456789.

Connect with a server-to-server app​

  1. In the Box Developer Console, create a separate Server app using Client Credentials Grant.
  2. Keep App Access Only selected. Enable file/folder read and write scopes. Extract does not need user management, group management, as-user calls, or user access-token generation.
  3. Submit the app for authorization and have your Box administrator approve it. On developer accounts, follow Box's authorization prompt if approval is not automatic.
  4. Find the app's Client ID and Client Secret. For the Enterprise ID, use the Developer Console's account menu → Copy Enterprise ID, or Admin Console → Account & Billing → Account Information.
  5. Grant the app's service account access to the destination folder, including permission to create subfolders and upload files. The service account is a separate identity from the person who created the app.
  6. In Extract, select Server-to-server app and enter the app's Client ID, Client Secret, Enterprise ID, and Root Folder ID. Save the destination.

The Enterprise ID identifies the organization that owns the service account. It is required even with App Access Only; it does not enable App + Enterprise Access.

See Box's CCG setup guide and ID lookup instructions.

File format and paths​

Choose CSV (the default), JSON Lines, or Parquet when creating a connection. CSV includes a header.

The default path, relative to the root folder, is:

{stream_name}/{year}/{month}/{day}/{stream_name}_{run_time}.{extension}

For example: Events/2026/10/25/Events_2026-10-25T14-00-00.123456Z.csv.

Extract creates missing subfolders. The default filename uses the persisted stream-run creation timestamp in UTC with microseconds. Date directory placeholders use UTC delivery time. For paths based on the source data's date or hour, use {cursor_year}, {cursor_month}, {cursor_day}, and {cursor_hour}. These are useful for hourly streams such as Singular User Level.

{run_time} stays stable for the same stream run. You can add {connection_name} to distinguish connections that write the same stream. Retain {run_time} in custom filenames to distinguish runs created within the same second. Custom paths using second-precision {timestamp} can collide. Existing saved paths are not changed automatically.

Keep {extension} in the template so that changing formats creates the correct suffix. Existing reports remain untouched. Paths must be relative, cannot contain empty or traversal segments, and must end with the selected format's extension.

Delivery behavior​

Extract stages a complete report before uploading it. A failed source does not publish a partial report. Large files use Box's chunked upload API; the account's upload-size limit still applies.

If a file already exists at the output path, Extract checks its size and SHA-1 digest. Matching content confirms a previous delivery; different content fails the run without modifying the existing file. A separately requested run can deliver the same source records again. Delivery-time paths can change across restarted runs, so this destination does not guarantee exactly-once delivery across different runs.

Troubleshooting​

  • App is not yet authorized for use: approve the CCG app in Box's Platform Apps Manager. Submitting the request alone does not authorize it.
  • Folder not found or access denied: check the folder ID and the authenticated identity's collaboration permissions. Sharing a folder with your own user does not grant access to an app service account.
  • Different file already exists: choose a unique output path or timestamp. Extract will not overwrite the existing report.
  • OAuth configuration missing: ask your Extract administrator to configure the shared Box application credentials.
  • OAuth expired: reconnect the destination. Box refresh tokens rotate; an interrupted renewal can require a new sign-in.