Box

Upload files to a Box folder in CSV or JSONL format. Use Zeotap to export audience lists, model results, or enriched data to Box for downstream collaboration and processing.

Prerequisites

• A Box account (Free, Business, or Enterprise)
• A Box custom app with OAuth 2.0 authentication, or a developer token for testing
• Editor or Co-owner access on the target folder

Authentication

Box supports two authentication methods:

OAuth 2.0 (Recommended)

OAuth 2.0 is the recommended method for production use. It provides automatic token refresh so your syncs continue without interruption.

1. In the Box Developer Console , create a Custom App with User Authentication (OAuth 2.0)
2. Under Configuration, note the Client ID and Client Secret
3. Add https://composable.zeotap.com/oauth/callback as a Redirect URI
4. Under Application Scopes, enable Write all files and folders stored in Box
5. In Zeotap, select OAuth 2.0 as the authentication method and click Connect
6. Authorize the app in the Box consent screen

Developer Token (Testing Only)

Developer tokens are convenient for testing but expire after 60 minutes.

1. In the Box Developer Console , open your app
2. Under Configuration, click Generate Developer Token
3. Copy the token and paste it into the Access Token field in Zeotap

Note: Developer tokens cannot be refreshed automatically. For production syncs, use OAuth 2.0.

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

Features

• Field Mapping: No — Box writes all mapped fields as file columns
• Schema Introspection: No — Box is a file-based destination without schema discovery

How It Works

Zeotap writes data as files to the configured Box folder:

1. Data is serialized into the selected format (CSV or JSONL)
2. Files are uploaded to the target folder via the Box Content API using multipart upload
3. Each file is named with a date prefix and batch ID: {YYYY-MM-DD}_batch_{timestamp}.{ext}
4. Each sync run produces a new file — existing files are never modified or deleted

Sync mode semantics

• Insert writes the full current dataset as a new file on every run.
• Mirror writes the full dataset on the first run, then only the rows that changed on later runs. Every row in a mirror-mode file carries an _operation column — added, changed, or removed — so downstream consumers can apply updates and deletions. On the first run all rows are marked added. In CSV files _operation is always the last column; treat the name as reserved in mirror mode.
• Add (audience syncs) writes only new and updated audience members. Members who left the audience since the previous run are excluded from the files.
• Snapshot writes the complete current dataset as new files on every run and never diffs. There is no _operation column (the files are the whole dataset) and unchanged rows are included every time. Records that left are simply absent from the next drop rather than delivered tagged removed, so treat each run’s output as authoritative and replace your prior copy rather than merging into it. Unlike Insert, snapshot is guaranteed to read the full model output on every warehouse: it never adopts native change tracking (Snowflake streams, Databricks CDF), which can only surface deltas.

File Size Limits

Box supports direct uploads up to 50 MB per file. For most syncs, this is more than sufficient. If a batch exceeds 50 MB, consider reducing the number of fields or splitting the sync into smaller audiences.

Rate Limits

Box enforces the following rate limits:

• 10 API calls per second per user
• 4 uploads per second per user
• HTTP 429 responses include a Retry-After header

Zeotap respects Box rate limits. If a 429 response is received, the sync will pause and retry after the specified delay.

Best Practices

• Use OAuth 2.0 for production syncs to ensure uninterrupted token refresh
• Create a dedicated folder for Zeotap uploads to keep data organized
• Use folder permissions to control who can access exported data
• Use JSONL format for large datasets — it is more efficient to parse than CSV for downstream processing
• Monitor folder size — Box storage limits vary by plan

Troubleshooting

Authentication failed (401)

Verify that your access token is valid. Developer tokens expire after 60 minutes. If using OAuth 2.0, try disconnecting and reconnecting the destination in Zeotap.

Folder not found (404)

Check that the folder ID is correct. Open the folder in Box and copy the numeric ID from the URL. Ensure the authenticated user has access to the folder.

Insufficient permissions (403)

The authenticated user needs Editor or higher access on the target folder. Ask the folder owner to grant you the appropriate role.

File name conflict (409)

This occurs if a file with the same name already exists in the folder. Zeotap automatically handles this by appending a unique suffix. If you see this error persistently, check for files from previous sync runs in the target folder.

Rate limited (429)

Box limits uploads to 4 per second per user. If syncing large audiences, this may cause temporary delays. Zeotap handles rate limiting automatically with backoff. For high-frequency syncs, consider using a service account dedicated to Zeotap.

Upload too large

Box direct uploads are limited to 50 MB. Reduce the number of mapped fields or split your audience into smaller segments to keep file sizes under the limit.