Search

Transferring Documents via Box (New Files)

Overview

This guide explains how to set up the Box (New Files) integration with Pramata. Once configured, Pramata automatically monitors the selected Box folder on a recurring schedule and transfers any new files uploaded after the integration is activated.

Prerequisites

For Box

  • A Box account with access to the folder containing the contracts you want to transfer.
  • Access to the Box Developer Console to create and configure a Box OAuth app.

For Pramata Platform

  • Ensure you have the necessary Admin rights to the Pramata Platform for completing the integration process.

Limitations

Please review these limitations before beginning the transfer to ensure a smooth experience.

Parameter Limit Details
Folders per account No limit Any number of top-level folders are supported. Use the URL/ID override field to select nested sub-folders at any depth.
File Format Accepted formats pdf, doc, docx, txt, jpg, jpeg, tiff, tif, rtf, html, htm, xls, xlsx, msg, png, csv, xlsm, zip
File Size 500 MB per file Files larger than 500 MB are automatically skipped and logged.
Sync frequency Configurable (default: hourly) New files are checked and transferred on the configured schedule.
First sync delay ~1 hour schedule cycle after setup The initial sync initializes the cursor — files added after this point are picked up on the next run.

Step 1: Create a Box OAuth App

Before configuring the integration in Pramata, you must create a Box OAuth application in the Box Developer Console.

Note: The steps below must be completed by your Box Administrator before end users can configure the integration

  1. Login to the Box Developer Console.
  2. Click Create New App
  3. Select Custom App and click Next
  4. Select User Authentication (OAuth 2.0) and click Next
  5. Enter an app name (e.g. Pramata Integration) and click Create App

Configure OAuth 2.0 Redirect URL

In your new app's Configuration tab, under OAuth 2.0 Redirect URIs, add:

https://oauth2.integrations.pramata.com/callback

Configure Application Scopes

Under Configuration → Application Scopes → Content Actions:

⚠️ Important — Both Read and Write must be enabled

✅Read all files and folders stored in Box

✅Write all files and folders stored in Box

Click Save Changes. Then copy the Client ID and Client Secret — you will need these in the next step.

Step 2: Integrate Box (New Files) with Pramata

Open Pramata and navigate to Admin Console → Integrations Hub → Box (New Files). Click Configure and complete the following steps in sequence:

Steps Pop-up Window What to Do
1 Initial Configuration The integration name is auto-populated. Review it and click Next.
2 Configuration Enter the Client ID and Client Secret from the Box Developer Console. Click Connect for the Box Connection.
3 Box Authorization A Box login window will open. Sign in with your Box account and authorize access. Once authorization completes, the status updates to Connected. Click Next.
4 Setup Overview Review the important notes about the sync behavior and click Next.
5 Select Folder Choose the Box folder to monitor. See Selecting a Folder below.
6 Schedule Set how frequently Pramata checks for new files (e.g. every 1 hour). Click Finish.

Selecting a Folder

The Select Folder step has two options depending on whether you need a top-level or nested folder.

Option 1 — Select from the dropdown (top-level folders)

The dropdown lists all top-level folders in your Box account. Simply pick the folder you want and click Next.

  • Selecting a parent folder will also include files from all of its sub-folders.

Option 2 — Paste a Box folder URL or ID (nested sub-folders)

If the folder you need is nested several levels deep, paste the folder URL or ID into the Box Folder URL or ID (Override) field.

The field accepts:

If a URL or ID is entered, it takes priority over the dropdown selection.

Sync Activation

Once you click Finish, the sync workflow is deployed and activated automatically.

  • First run: Initializes the sync cursor to the current point in time. No files are transferred on the first run.
  • Subsequent runs: Pramata checks the Box Events stream for new file uploads since the last cursor position. Any new files in the configured folder are transferred.

Note: Files already present in the folder at the time of setup are NOT transferred by the New Files sync. Only files uploaded after the integration is first deployed will be picked up.

Transfer History

After transfers complete, view results by clicking Transfer History on the Box (New Files) card. The Transfer History displays:

  • Status of each sync cycle (Completed, In Progress, Failed)
  • Number of files transferred per sync cycle
  • The folder path from which files were transferred
  • Timestamp of each sync cycle

During active transfers, the card will show a Transfer in Progress badge and Transfer History will display a Processing files... indicator.

Reconfiguring the Sync

To change the monitored folder or any other setting, click Configure on the Box (New Files) card. The existing Box connection will be preserved. You can update the Folder selection without needing to re-authorize Box.

Frequently Asked Questions

Q: Will files already be in the Box folder when I set up the integration be transferred?

A: No. The New Files integration only picks up files uploaded after the first sync run. Files that were already in Box before the integration was deployed are not transferred.
 

Q: Why does the Box app need the "Write all files" scope enabled if Pramata only reads files?

A: This is a requirement of Box's platform, not Pramata's design. Box's official OAuth2 Scopes documentation states that the root_readwrite scope is required to "download content" via the API. Box's Developer Console also states directly under the Write scope: "Necessary to download files and folders."

The item_download scope (a download-only alternative) is listed in Box's documentation as a downscoping scope and is not supported as a primary OAuth scope for new Platform Apps — requesting it returns an invalid_scope error.

Pramata's integration never creates, modifies, or deletes any files or folders in your Box account — the Write scope is solely required for Box to permit content downloads via its API.
 

Q: Is there a limit on the number of folders in my Box account?

A: No. Any number of top-level folders are supported. Nested folders at any depth can be selected using the URL or ID override field.
 

Q: What happens if a file is larger than 500 MB?

A: Files over 500 MB are automatically skipped and logged. They will not be retried.
 

Q: If a file is uploaded to Box and then deleted before the next sync, will it be transferred?

A: If the file was uploaded after the cursor was initialized, Pramata will attempt to download it. If it has been deleted from Box by the time the sync runs, the download will fail and the file will be logged as failed.
 

Q: Can the same file be transferred twice?

A: No. The integration performs a duplicate check before processing each file. If a file has already been successfully ingested into Pramata, it will be skipped on subsequent runs.