Data Structure
Files and Permissions
Box's data structure consists of folders and files but does not include drives. Access to files and folders is managed through permissions (also known as Access Control Lists or ACLs), granted to users and groups.
Each Box instance includes a root level named "All Files.” Because of Box API limitations, Merge cannot map this root level to a specific folder, so files located here are synced with a null parent_folder id.
Checksums
Box provides a checksum called "sha1" to verify if file contents have changed. Merge directly maps this checksum from the Box API rather than generating it internally.
Users
Users represent individuals with access to the Box instance. Users can gain access through group memberships or by direct collaboration on files or folders, even if they are external to the Box instance.
Ingestion
Sync Cadence
Merge regularly polls the Box API at intervals defined in the provided table for updates to all common models. Sync frequency is constrained by Box API rate limits. Merge employs timestamp filtering to ensure polling efficiency.
If the highest available sync frequency listed does not meet your requirements, please contact us to discuss custom sync options.
Webhooks
Beyond periodic polling, Merge leverages Box webhooks to capture real-time updates on files, folders, and permissions when available. These webhooks have many limitations based on what Box supports:
When folder-level permissions change (e.g., ownership, shared access), Merge receives a webhook notification for the affected folder. However, Box does not send webhook notifications for permission changes affecting nested items within the folder. These cascading changes are captured in subsequent polling events
Box does not allow webhook subscriptions for actions performed at the root (“All Files”) level. Consequently, creation events at this level do not trigger webhooks
Merge subscribes to webhooks for newly created folders; however, webhook subscription setup may experience delays of up to 3 hours (due to Box delays) after folder creation
Webhook notifications for changes involving Users or Groups are not supported by Box
Given these constraints, webhook notifications alone cannot fully guarantee data accuracy and completeness for Box. Regular polling should always serve as the baseline method for maintaining data freshness in your application.
Mime Types
Box does not support specifying MIME types when downloading file contents. Merge returns files in their original format via our /download and /direct-download endpoints.
Rate Limits
Box enforces two types of rate limits:
1,000 API requests per minute
100,000 API requests per month (Enterprise Plan)
Authentication
Supported Authentication Types
Merge supports three authentication types with Box and will initiate an OAuth flow prompting your users to enter their username and password for any option. Box mandates write permissions for files and folders to enable downloading through their API which all three authentication types support.
The admin-level connections must have “Read and write for admins” or “Read and write for super admins” permissions enabled. Box developer support confirms there are currently no alternative solutions.
1. Read and Write for Super Admins
Only Box super admins can authenticate using this method. Super admins have permissions to allow the super admin to make authenticated requests on behalf of another user to access private user files and folders.
2. Read and Write for Admins
Only Box administrators can authenticate using this method. Admins generally have access to a broader set of public files and folders.
3. Read and Write for Non-Admins
Any user with valid Box credentials can authenticate using this method. Access is limited to the authenticated user's personal drive, as well as shared drives and explicitly shared files.