> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/files-and-tables/box.md).

# Box

Connect Box to Google Sheets, BigQuery, or AI tools via Coupler.io. Export files, users, admin logs, sign requests, and more.

Box is a cloud content management platform where teams store, share, and collaborate on files and documents. It's widely used for document workflows, file-level access control, and enterprise content governance.

Connecting Box to Coupler.io lets you pull your content metadata, user activity, and signing workflows into spreadsheets, data warehouses, or AI tools for analysis and reporting.

**Why connect Box to Coupler.io?**

* Audit file and folder access by exporting collaboration permissions across your organization
* Track document signing workflows by syncing sign requests and sign templates
* Monitor user activity and compliance using admin logs and event streams
* Combine Box data with other sources using Join or Append transformations for richer reporting

## Prerequisites

* A Box developer account with an app configured for Client Credentials Grant (CCG) authentication
* A **Client ID**, **Client Secret**, and **Enterprise ID** (or **User ID**) from your Box app settings
* Your Box app must have the appropriate scopes enabled (e.g., `admin_readwrite` for admin logs)

{% hint style="success" %}
If you're auditing file access or tracking sign requests, start with the **File collaborations** and **Sign requests** entities — they give you the most actionable data right away.
{% endhint %}

## Quick start

{% stepper %}
{% step %}
**Create a new data flow in Coupler.io.** From your Coupler.io dashboard, click **Add data flow** and search for **Box** as your source.
{% endstep %}

{% step %}
**Enter your Box API credentials.** You'll need your Client ID and Client Secret from your Box developer app. Coupler.io uses these to authenticate via the Client Credentials Grant flow. Paste them into the corresponding fields.
{% endstep %}

{% step %}
**Enter your User ID.** Specify the Box User ID you want to authenticate as. You can find this in your Box developer console or via the Box API. This tells Coupler.io which account context to use when fetching data.
{% endstep %}

{% step %}
**Select an entity.** Choose which Box data you want to pull — for example, **Files**, **Users**, **Admin logs**, or **Sign requests**. Each entity maps to a specific set of Box data.
{% endstep %}

{% step %}
**Choose a destination.** Select where you want your Box data to land — Google Sheets, Excel, BigQuery, Looker Studio, or an AI tool like ChatGPT, Claude, or Gemini.
{% endstep %}

{% step %}
**Run your data flow.** Click **Run** to execute a manual sync. Once it completes successfully, your Box data will appear in your chosen destination.
{% endstep %}
{% endstepper %}

## Box data overview

Coupler.io can pull 15 distinct entities from Box, covering file storage, access control, user management, activity logs, and document signing. Here's a breakdown of what's available and what you can do with it.

## Available entities

| Entity                | What it contains                                            |
| --------------------- | ----------------------------------------------------------- |
| Events                | Activity log events tied to users or the enterprise         |
| Admin logs            | Enterprise-level administrative actions and audit trail     |
| Files                 | Metadata for files stored in Box (name, size, owner, dates) |
| Folders               | Folder structure and metadata                               |
| File collaborations   | Access permissions granted on individual files              |
| Folder collaborations | Access permissions granted on folders                       |
| File comments         | User comments attached to files                             |
| File tasks            | Tasks assigned to files (assignee, due date, status)        |
| Collections           | Named groups of content                                     |
| Collection items      | Files or folders inside a collection                        |
| Sign requests         | Document signing requests and their status                  |
| Sign templates        | Reusable signing workflow templates                         |
| Users                 | User accounts, roles, and profile details                   |
| Recent items          | Files and folders recently accessed by the user             |
| Trashed items         | Items pending deletion in the trash                         |

## Metrics and dimensions by entity

#### Files

| Field        | Type      | Description                     |
| ------------ | --------- | ------------------------------- |
| id           | Dimension | Unique file identifier          |
| name         | Dimension | File name                       |
| size         | Metric    | File size in bytes              |
| created\_at  | Dimension | File creation timestamp         |
| modified\_at | Dimension | Last modified timestamp         |
| owned\_by    | Dimension | Owner user ID and name          |
| parent       | Dimension | Parent folder ID and name       |
| item\_status | Dimension | Active, trashed, or deleted     |
| shared\_link | Dimension | Sharing link details if enabled |

#### Users

| Field         | Type      | Description                   |
| ------------- | --------- | ----------------------------- |
| id            | Dimension | Unique user identifier        |
| name          | Dimension | Full name                     |
| login         | Dimension | Email address used to log in  |
| role          | Dimension | User role (admin, user, etc.) |
| space\_used   | Metric    | Storage used in bytes         |
| space\_amount | Metric    | Total storage quota           |
| status        | Dimension | Active or inactive            |
| created\_at   | Dimension | Account creation date         |

#### Admin logs

| Field       | Type      | Description                        |
| ----------- | --------- | ---------------------------------- |
| event\_id   | Dimension | Unique event ID                    |
| event\_type | Dimension | Type of admin action               |
| created\_at | Dimension | Timestamp of the event             |
| created\_by | Dimension | User who triggered the event       |
| source      | Dimension | Object the action was performed on |
| ip\_address | Dimension | IP of the session                  |

#### Sign requests

| Field         | Type      | Description                                |
| ------------- | --------- | ------------------------------------------ |
| id            | Dimension | Unique sign request ID                     |
| status        | Dimension | Request status (pending, signed, declined) |
| signers       | Dimension | List of signers and their status           |
| source\_files | Dimension | Files being signed                         |
| created\_at   | Dimension | Request creation time                      |
| sign\_files   | Dimension | Completed signed document references       |

#### File & folder collaborations

| Field          | Type      | Description                              |
| -------------- | --------- | ---------------------------------------- |
| id             | Dimension | Collaboration record ID                  |
| item           | Dimension | File or folder being shared              |
| accessible\_by | Dimension | User or group with access                |
| role           | Dimension | Permission level (viewer, editor, owner) |
| status         | Dimension | Accepted, pending, or rejected           |
| created\_at    | Dimension | When collaboration was created           |

#### Events

| Field       | Type      | Description                                 |
| ----------- | --------- | ------------------------------------------- |
| event\_id   | Dimension | Unique event identifier                     |
| event\_type | Dimension | Action type (UPLOAD, DOWNLOAD, LOGIN, etc.) |
| created\_at | Dimension | Event timestamp                             |
| created\_by | Dimension | User who performed the action               |
| source      | Dimension | Item the action involved                    |

## Common metric combinations

* **Users + File collaborations** — Join on user ID to see which users have access to which files and at what permission level
* **Events + Users** — Match event creators to user profiles for a full activity audit with names and roles
* **Sign requests + Sign templates** — Understand which templates drive the most signing activity and where requests stall
* **Admin logs + Users** — Correlate admin actions with specific accounts for compliance reporting

## Use cases by role

{% tabs %}
{% tab title="IT & Security" %}

* Export **File collaborations** and **Folder collaborations** to audit who has access to sensitive folders across the organization
* Pull **Admin logs** into BigQuery to build a compliance dashboard tracking permission changes, logins, and deletions
* Use **Events** to detect unusual download or sharing activity by user
  {% endtab %}

{% tab title="Operations" %}

* Track **Sign requests** by status to monitor which contracts or documents are pending signature
* Use **File tasks** to report on open task assignments and due dates across teams
* Export **Users** and their storage usage to manage licensing and quota allocation
  {% endtab %}

{% tab title="Legal & Compliance" %}

* Combine **Admin logs** and **Events** using Append in Coupler.io to build a full audit trail in one sheet
* Monitor **Trashed items** to catch accidental or unauthorized deletions before they're purged
* Pull **Sign templates** and **Sign requests** to verify that correct templates are being used for regulated documents
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* Admin logs and Events are only available to Box Enterprise accounts — they won't appear for individual or Business Starter plans
* The **User ID** parameter determines which user's context is used for the sync; data scope varies depending on whether that user is an admin
* Recent items reflects the authenticated user's activity only, not organization-wide access
* Trashed items are permanently deleted after Box's retention period, so sync frequently if you need a record
* Sign requests and Sign templates require Box Sign to be enabled on your account

## Box common issues

### Connection issues

<details>

<summary>Authentication fails when entering API credentials</summary>

Double-check that you're using the **Client ID** and **Client Secret** from a Box app configured with **Client Credentials Grant (CCG)**. Apps using OAuth 2.0 user authentication won't work here. Make sure the app has been authorized by your Box enterprise admin if you're accessing enterprise-level data.

</details>

<details>

<summary>The data flow runs but returns no data</summary>

This usually means the User ID is missing or incorrect. The **User ID** field tells Coupler.io which Box account to authenticate as. Verify the ID in your Box developer console under your app's service account details. Without a valid User ID, the connection may succeed but return empty results.

</details>

### Missing data

<details>

<summary>Admin logs or Events entity returns no rows</summary>

Admin logs and Events are only available on **Box Enterprise** plans. If your account is on a lower tier, these entities won't return data. Also confirm that your Box app has the `manage_enterprise` or `admin_readwrite` scope enabled — without it, the API call will succeed but return nothing.

</details>

<details>

<summary>Sign requests or Sign templates are empty</summary>

Box Sign must be enabled on your account. If your organization hasn't activated Box Sign, these entities will return no data. Check with your Box admin to confirm Sign is part of your subscription.

</details>

<details>

<summary>Trashed items aren't showing up</summary>

Trashed items are only visible within Box's retention window — once permanently deleted, they can't be retrieved via the API. If items were purged before your sync ran, they won't appear. Run your data flow more frequently to capture trash contents before purge.

</details>

### Permission errors

<details>

<summary>"Insufficient permissions" error on specific entities</summary>

This means the user specified in the **User ID** field doesn't have access to that entity. For admin-only entities like Admin logs, the User ID must belong to a Box co-admin or admin. For file-level entities, the user must have at least viewer access to the relevant content.

{% hint style="warning" %}
Switching to an admin User ID will broaden data access but may expose sensitive audit data. Confirm with your security team before changing this setting.
{% endhint %}

</details>

<details>

<summary>App not authorized for enterprise access</summary>

Enterprise-scoped entities require your Box app to be explicitly authorized by a Box enterprise admin in the **Admin Console → Apps → Custom Apps**. If authorization is missing, the API returns a permission error even if credentials are correct.

</details>

### Data discrepancies

<details>

<summary>File counts in Coupler.io don't match what I see in Box</summary>

The Box API returns data scoped to the authenticated user. If the User ID belongs to a regular user rather than an admin, only files that user has access to will appear. Switch to an admin-level User ID to get a broader view of all files in the enterprise.

</details>

<details>

<summary>Collaboration roles look different from what's shown in the Box UI</summary>

Box uses internal role labels in the API (e.g., `co-owner`, `editor`, `viewer uploader`) that may differ slightly from what's displayed in the Box web interface. These are accurate API values — refer to Box's API documentation for the full role mapping.

</details>

### Rate limits

<details>

<summary>Sync fails or slows down with large numbers of files or events</summary>

Box enforces API rate limits per app. If you're syncing large entities like Files or Events across a big enterprise, you may hit these limits. Try splitting your data flow into multiple flows per entity rather than pulling everything at once, and avoid running multiple flows simultaneously.

</details>

## Box FAQ

<details>

<summary>What authentication method does Box use in Coupler.io?</summary>

Box uses an API key / Client Credentials Grant (CCG) flow. You'll need a Client ID and Client Secret from a Box developer app configured for CCG, along with a User ID to specify which account context to authenticate as. This is different from the standard OAuth login flow.

</details>

<details>

<summary>Where do I find my Box User ID?</summary>

You can find your User ID in the Box developer console under your app's service account, or by calling the Box `/users/me` API endpoint. Your enterprise admin can also look it up in the Box Admin Console under **Users & Groups**.

</details>

<details>

<summary>Can I export Box Admin logs into a spreadsheet or database?</summary>

Yes — the **Admin logs** entity gives you the full enterprise audit trail. You can send it to Google Sheets, Excel, BigQuery, or any other supported destination. For ongoing compliance reporting, use Append mode in your destination so logs accumulate over time rather than being overwritten.

</details>

<details>

<summary>Why do I see data for some entities but not others?</summary>

Data availability depends on your Box plan and the permissions of the User ID you're using. Admin logs and Events require a Box Enterprise plan and an admin-level user. Sign requests and Sign templates require Box Sign to be enabled. File-level entities are scoped to what the authenticated user can access.

</details>

<details>

<summary>Can I combine data from multiple Box entities in one report?</summary>

Absolutely. Use Coupler.io's **Join** transformation to combine entities like Users and File collaborations on a shared user ID field. You can also use **Append** to stack data from the same entity across multiple Box accounts into a single destination sheet.

</details>

<details>

<summary>Can I send Box data to an AI tool like ChatGPT or Claude?</summary>

Yes — Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw. This is useful for summarizing activity logs, analyzing sign request patterns, or getting insights from file metadata without building a full dashboard.

</details>

<details>

<summary>Does Coupler.io sync the actual file contents from Box?</summary>

No — Coupler.io syncs file **metadata** (name, size, owner, timestamps, sharing settings), not the raw file contents. If you need to process document content, you'd need to download files directly from Box.

</details>

<details>

<summary>How do I track which users have access to a specific folder?</summary>

Pull the **Folder collaborations** entity, which returns every collaboration record per folder including the user or group with access and their permission role. Join this with the **Users** entity in Coupler.io to replace user IDs with names and email addresses for a readable access report.

</details>

{% hint style="info" %}
For a full list of available fields per entity, see the [Data Overview](#box-data-overview) page. For help with missing data or permission errors, check the [Common Issues](#box-common-issues) guide.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/files-and-tables/box.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
