> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Route claims evidence for review with Box Automate
> Build a claims service that runs an automated approval workflow. Box handles the approval or rejection of tasks. Your app chooses the files and starts the review.
export const RelatedLinks = ({title, items = []}) => {
const getBadgeClass = badge => {
if (!badge) return "badge-default";
const badgeType = badge.toLowerCase().replace(/\s+/g, "-");
return `badge-${badge === "ガイド" ? "guide" : badgeType}`;
};
if (!items || items.length === 0) {
return null;
}
return
;
};
export const Link = ({href, children, className, ...props}) => {
const localizedHref = localizeLink(href);
return
{children}
;
};
A claims system collects evidence into a case folder: photos, police reports, repair estimates, medical records. Someone has to decide whether that evidence is complete and acceptable. That decision then has to be recorded.
This tutorial hands the review to Box. When your app calls `POST /reviews` with selected evidence file IDs, the service tags those files with the claim ID and begins a Box Automate workflow. Box Automate assigns the approval task, waits for the decision, then runs the approved or rejected branch.
Prefer to start from running code? The complete app built in this tutorial is on GitHub. Clone it, add your Box credentials, and run.
The Box Automate workflow endpoints used in this tutorial are **Beta** and are not available on the Free Developer Plan. Every request must include the `box-version: 2026.0` header. Beta endpoints can change before general availability.
## What you are building
By the end of this tutorial, you have a working Python service that:
* Exposes a `POST /reviews` endpoint your claims system uses to start a review on selected evidence files.
* Writes the claim ID onto each selected evidence file as Box metadata, so the workflow can read it as a variable.
* Looks up the published Automate workflow attached to the claims folder and starts it on the selected files.
Box Automate owns the review itself. Your service never polls for task state or implements approval logic.
| Component | Purpose | API |
| ----------------------------- | ----------------------------------------------------------------- | ----------------------------------------------- |
| **Automate workflow actions** | Find the published workflow attached to the claims folder | `GET /2.0/automate_workflows` |
| **Manual start** | Start the approve and reject tasks on the selected evidence files | `POST /2.0/automate_workflows/:id/start` |
| **Metadata** | Carry the claim ID into the workflow as a variable | `POST /2.0/files/:id/metadata/:scope/:template` |
**Why metadata carries the claim ID.** During the Beta, the start endpoint does not accept fields at runtime, so you cannot pass a claim ID in the request body. Writing the claim ID to each file as metadata makes it available as a workflow variable. When fields at start become available, you can pass the claim ID directly and drop this step.
## Prerequisites
Before you start, make sure you have the following:
* A Box Enterprise Advanced account with **Box Automate** enabled. See Enabling Box Automate.
* A Box platform application configured with **Client Credentials Grant** authentication, with **Read and write all files and folders stored in Box** enabled, **App + Enterprise Access**, and **Generate user access tokens** turned on. After you change those settings, re-authorize the app in the Admin Console.
* The **user ID** of a managed user who can build and start Automate workflows (for testing, use your own user ID). The Automate list and start endpoints return workflows that user can start. They do not return results for the enterprise service account.
* **Admin access** to create a metadata template, or a Box administrator who can create one for you.
* Permission to build and publish workflows in the Box Automate builder.
* Python 3.11 or higher.
* A coding agent with Box Agent Skills installed. Run `npx skills add box/box-for-ai` in your project, or install the Cursor, Codex, or Claude Code plugin. See Box Agent Skills for setup.
Both Automate endpoints require `root_readwrite`, the OAuth scope behind **Read and write all files and folders stored in Box**. The same scope covers writing claim metadata. If a scope or feature is missing from the Developer Console, contact Box Support with the user or app context you plan to use.
## Configure Box once
These steps happen in the Box Admin Console and Automate builder. An agent cannot do them for you. Complete them before you build the service.
1. **Create a `Claim` metadata template** in the [Admin Console](https://app.box.com/master) under **Metadata**. Add two text fields: Claim ID and Review status. Click **Save**, click back into the template, then copy the template key. Confirm the generated field keys with `GET /2.0/metadata_templates/enterprise//schema`. This tutorial assumes `claimId` and `reviewStatus`.
2. **Configure Client Credentials Grant for a managed user.** In Developer Console > your CCG app > **Configuration**, set application access to **App + Enterprise Access**, enable **Generate user access tokens**, and save. Re-authorize the app in the Admin Console. Copy the managed user's ID (Admin Console > Users & Groups, or `GET /2.0/users/me` with that user's token). You pass this ID as `BOX_USER_ID` so the service authenticates as that user, not as the enterprise service account.
A service-account token can often read the claims folder and write metadata, yet `GET /2.0/automate_workflows` still returns an empty `entries` list, and start returns `400 Action not found`. Authenticate as a managed user who can run Automate.
3. **Create a `Claims Review` folder** in Box as that managed user (or invite them as an **Editor**), note its folder ID from the URL, and upload two or three sample PDFs. Without folder access for the user your app acts as, file and metadata calls return 404.
4. **Build and publish a Manual Start workflow** in the Box Automate builder. For a full walkthrough of the builder UI, see Creating workflows in Box Automate.
1. Open **Automate**, select **New+** → **Workflow**, and name it `Claims evidence review`.
2. Drag **Manual Start** onto the canvas and scope it to the `Claims Review` folder.
3. Add a **Task Action** outcome. Set the type to **Approval**, assign the file to **Trigger: File**, and for testing set both complete and manage to **Workflow owner**. Optionally include the Claim ID metadata field in the task message.
4. Branch on **Approved** and **Rejected**, and add **Send Notification** on each branch.
5. Select **Activate** (not only **Save**).
The Manual Start folder must match the `folder_id` you query later. An unpublished draft, or a different folder, returns an empty `entries` list rather than an error.
5. **Optional: inspect the workflow IDs** so you recognize the response shape later. Use an access token for the same managed user your app will act as:
```bash theme={null}
curl -X GET "https://api.box.com/2.0/automate_workflows?folder_id=" \
-H "box-version: 2026.0" \
-H "Authorization: Bearer "
```
| Response field | Where it goes |
| ----------------------- | ------------------------------- |
| `entries[].workflow.id` | Path parameter `workflow_id` |
| `entries[].id` | Body field `workflow_action_id` |
The top-level `id` is the **action** ID, not the workflow ID. Passing the action ID in the path returns a 404.
## Build the service
Choose how to scaffold the service. Both paths produce the same app; continue to [Run and verify](#run-and-verify) when you finish.
Prefer not to build the project step by step? Clone the sample code for this tutorial and run it directly.
With Box configured and Box Agent Skills installed, paste the following prompt into your coding agent. Replace the placeholders only if you want the agent to pre-fill `.env`; otherwise leave them and fill credentials yourself after scaffolding.
```text theme={null}
Build a Python Flask service named claims-evidence-review that starts a Box
Automate manual-start workflow when POST /reviews receives selected evidence
file IDs.
Prerequisites already done in Box:
- Enterprise metadata template key: (fields claimId, reviewStatus)
- Folder ID for Manual Start:
- Published Automate workflow named exactly: Claims evidence review
- CCG app has read/write files scope, App + Enterprise Access, and Generate
user access tokens enabled and re-authorized
- Managed user ID for Automate calls: (not the service account)
Create these files:
1. box_client.py — CCG BoxClient from BOX_CLIENT_ID, BOX_CLIENT_SECRET,
and BOX_USER_ID via python-dotenv. Authenticate as the managed user
(CCGConfig user_id). Do NOT use enterprise_id / the service account;
Automate list and start return empty or Action not found for that actor.
2. automate.py — wrap the Beta Automate APIs with client.make_request
(box-sdk-gen has no automate_workflows manager yet):
- Always send header box-version: 2026.0
- GET https://api.box.com/2.0/automate_workflows?folder_id=...
- Map each entry to WorkflowAction(workflow_id=entry.workflow.id,
action_id=entry.id, name=entry.workflow.name)
- find_workflow_action(client, folder_id, workflow_name) raises LookupError
with a clear message if none match
- start_workflow POSTs to
/2.0/automate_workflows/{workflow_id}/start with body
{ "workflow_action_id": action_id, "file_ids": [...] }
- MAX_FILES_PER_RUN = 20
- Do NOT use legacy /2.0/workflows or invent folder/flow/outcomes fields
3. claims_metadata.py — for each file_id, create enterprise metadata with
{ claimId, reviewStatus: "in_review" }. On 409 Conflict, JSON-Patch replace
both fields (resubmitted evidence).
4. app.py — POST /reviews accepts { claim_id, file_ids }. Validate inputs,
tag metadata first, resolve workflow by BOX_CLAIMS_WORKFLOW_NAME on
BOX_CLAIMS_FOLDER_ID, start workflow, return 202
{ status, claim_id, workflow, file_ids }.
5. .env.example and .gitignore (.env excluded). Env vars:
BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_USER_ID,
BOX_CLAIMS_FOLDER_ID, BOX_CLAIMS_TEMPLATE_KEY, BOX_CLAIMS_WORKFLOW_NAME
Use Python 3.11+, box-sdk-gen, flask, python-dotenv. Create a venv, install
deps, and print the curl command to test POST /reviews after I fill .env.
```
When the agent finishes, copy `.env.example` to `.env` and fill in your credentials, user ID, folder ID, and template key. Put each variable on its own line.
Prefer to write the code yourself, or need a reference when the agent drifts? Complete [Configure Box once](#configure-box-once) first, then follow the steps in order.
1. Create a project directory:
```bash theme={null}
mkdir claims-evidence-review && cd claims-evidence-review
```
2. Create and activate a Python virtual environment:
```bash theme={null}
python3 -m venv .venv
source .venv/bin/activate
```
After activation, your terminal prompt shows `(.venv)` at the beginning.
Every time you open a new terminal window or tab, re-activate with `source .venv/bin/activate`. `ModuleNotFoundError` usually means the venv is not activated.
3. Install packages:
```bash theme={null}
pip install box-sdk-gen flask python-dotenv
```
4. Create a `.env` file:
```bash theme={null}
BOX_CLIENT_ID=your_client_id
BOX_CLIENT_SECRET=your_client_secret
BOX_USER_ID=your_managed_user_id
BOX_CLAIMS_FOLDER_ID=your_claims_review_folder_id
BOX_CLAIMS_TEMPLATE_KEY=your_metadata_template_key
BOX_CLAIMS_WORKFLOW_NAME=Claims evidence review
```
Never commit `.env` files to version control. Add `.env` to your `.gitignore`.
Create `box_client.py`:
```python theme={null}
import os
from box_sdk_gen import BoxCCGAuth, BoxClient, CCGConfig
from dotenv import load_dotenv
load_dotenv()
def get_box_client() -> BoxClient:
config = CCGConfig(
client_id=os.getenv("BOX_CLIENT_ID"),
client_secret=os.getenv("BOX_CLIENT_SECRET"),
user_id=os.getenv("BOX_USER_ID"),
)
return BoxClient(auth=BoxCCGAuth(config=config))
```
Client Credentials Grant with `user_id` authenticates as that managed user. The Automate Manual Start endpoints return workflows that user can start. Do not use `enterprise_id` here: the enterprise service account can access the folder yet still sees an empty Automate list. For other options, see Select an authentication method.
Create `automate.py`. This module wraps both Automate endpoints and turns the nested list response into a small value object, so the rest of your app never handles the two raw IDs.
```python theme={null}
from dataclasses import dataclass
from box_sdk_gen import BoxClient
from box_sdk_gen.networking.fetch_options import FetchOptions, ResponseFormat
BOX_API_BASE = "https://api.box.com/2.0"
AUTOMATE_HEADERS = {"box-version": "2026.0"}
MAX_FILES_PER_RUN = 20
@dataclass(frozen=True)
class WorkflowAction:
"""A published Automate workflow that can be started through the API."""
workflow_id: str
action_id: str
name: str
def list_workflow_actions(client: BoxClient, folder_id: str) -> list[WorkflowAction]:
response = client.make_request(
FetchOptions(
url=f"{BOX_API_BASE}/automate_workflows",
method="GET",
params={"folder_id": folder_id},
headers=AUTOMATE_HEADERS,
response_format=ResponseFormat.JSON,
)
)
return [
WorkflowAction(
workflow_id=entry["workflow"]["id"],
action_id=entry["id"],
name=entry["workflow"].get("name", ""),
)
for entry in response.data.get("entries") or []
]
def find_workflow_action(
client: BoxClient, folder_id: str, workflow_name: str
) -> WorkflowAction:
actions = list_workflow_actions(client, folder_id)
if not actions:
raise LookupError(
f"No Automate workflow actions on folder {folder_id}. Confirm the "
"workflow is published and its Manual Start trigger uses this folder."
)
for action in actions:
if action.name == workflow_name:
return action
available = ", ".join(sorted(action.name for action in actions))
raise LookupError(
f"Workflow {workflow_name!r} not found on folder {folder_id}. "
f"Available workflows: {available}."
)
def start_workflow(
client: BoxClient, action: WorkflowAction, file_ids: list[str]
) -> None:
client.make_request(
FetchOptions(
url=f"{BOX_API_BASE}/automate_workflows/{action.workflow_id}/start",
method="POST",
headers=AUTOMATE_HEADERS,
data={"workflow_action_id": action.action_id, "file_ids": file_ids},
response_format=ResponseFormat.JSON,
)
)
```
The Automate endpoints are not yet in the generated Python SDK, so this module uses `client.make_request`. The SDK still handles token refresh, retries, and error mapping to `BoxAPIError`. When the endpoints reach the SDK, swap the two `make_request` calls for generated methods and leave the rest of the app untouched.
A successful start returns `204 No Content`. Treat a non-raising call as confirmation that Box accepted the run.
Create `claims_metadata.py`. This writes the claim context onto each file before the workflow starts.
```python theme={null}
import os
from box_sdk_gen import (
BoxAPIError,
BoxClient,
CreateFileMetadataByIdScope,
UpdateFileMetadataByIdRequestBody,
UpdateFileMetadataByIdRequestBodyOpField,
UpdateFileMetadataByIdScope,
)
from dotenv import load_dotenv
load_dotenv()
HTTP_CONFLICT = 409
def tag_evidence(client: BoxClient, file_ids: list[str], claim_id: str) -> None:
"""Attach claim context to each evidence file so the workflow can read it."""
template_key = os.getenv("BOX_CLAIMS_TEMPLATE_KEY")
values = {"claimId": claim_id, "reviewStatus": "in_review"}
for file_id in file_ids:
try:
client.file_metadata.create_file_metadata_by_id(
file_id=file_id,
scope=CreateFileMetadataByIdScope.ENTERPRISE,
template_key=template_key,
request_body=values,
)
except BoxAPIError as error:
if error.response_info.status_code != HTTP_CONFLICT:
raise
_replace_metadata(client, file_id, template_key, values)
def _replace_metadata(
client: BoxClient, file_id: str, template_key: str, values: dict[str, str]
) -> None:
"""Overwrite an existing instance, for evidence resubmitted on the same claim."""
client.file_metadata.update_file_metadata_by_id(
file_id=file_id,
scope=UpdateFileMetadataByIdScope.ENTERPRISE,
template_key=template_key,
request_body=[
UpdateFileMetadataByIdRequestBody(
op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,
path=f"/{key}",
value=value,
)
for key, value in values.items()
],
)
```
A file that already carries an instance of the template returns `409 Conflict` on create. The handler falls back to replacing the values so a restarted review does not fail.
Create `app.py`. This is the endpoint your claims system calls to start a review on selected evidence files.
```python theme={null}
import os
from dotenv import load_dotenv
from flask import Flask, jsonify, request
from automate import MAX_FILES_PER_RUN, find_workflow_action, start_workflow
from box_client import get_box_client
from claims_metadata import tag_evidence
load_dotenv()
app = Flask(__name__)
@app.post("/reviews")
def start_review():
payload = request.get_json(silent=True) or {}
claim_id = payload.get("claim_id")
file_ids = payload.get("file_ids") or []
if not claim_id:
return jsonify({"error": "claim_id is required"}), 400
if not file_ids:
return jsonify({"error": "file_ids must list at least one file"}), 400
if len(file_ids) > MAX_FILES_PER_RUN:
return jsonify(
{"error": f"Box Automate accepts at most {MAX_FILES_PER_RUN} files per run"}
), 400
client = get_box_client()
folder_id = os.getenv("BOX_CLAIMS_FOLDER_ID")
workflow_name = os.getenv("BOX_CLAIMS_WORKFLOW_NAME")
tag_evidence(client, file_ids, claim_id)
action = find_workflow_action(client, folder_id, workflow_name)
start_workflow(client, action, file_ids)
return jsonify(
{
"status": "review_started",
"claim_id": claim_id,
"workflow": action.name,
"file_ids": file_ids,
}
), 202
if __name__ == "__main__":
app.run(port=5000)
```
Tag metadata before starting the workflow. A workflow variable can only read metadata that already exists on the file.
Project layout:
```text theme={null}
claims-evidence-review/
├── .env
├── .venv/
├── app.py
├── automate.py
├── box_client.py
└── claims_metadata.py
```
Then continue to [Run and verify](#run-and-verify).
## Run and verify
1. Start the server (venv activated):
```bash theme={null}
python3 app.py
```
2. In a second terminal, start a review. Use file IDs from the sample PDFs in `Claims Review`, not the folder ID:
```bash theme={null}
curl -X POST http://127.0.0.1:5000/reviews \
-H "Content-Type: application/json" \
-d '{
"claim_id": "CLM-1042",
"file_ids": ["123456789", "987654321"]
}'
```
A successful response looks like:
```json theme={null}
{
"status": "review_started",
"claim_id": "CLM-1042",
"workflow": "Claims evidence review",
"file_ids": ["123456789", "987654321"]
}
```
3. Confirm in Box:
* Open an evidence file → **Metadata** tab shows claim `CLM-1042` and status `in_review`.
* As the task assignee, open the approval task and confirm the claim ID appears in the message.
* Approve or reject from the file's **Activity** sidebar panel, and confirm the matching branch runs.
## Troubleshooting
Your virtual environment is not activated. Run `source .venv/bin/activate` from the project directory before running any `python3` commands. Each new terminal tab needs its own activation.
Check your `.env` file:
* Verify `BOX_CLIENT_ID` and `BOX_CLIENT_SECRET` match the values in Developer Console > Configuration.
* Ensure the app is authorized and its type is Client Credentials Grant.
Your app is requesting a user token, but the Developer Console is not set up for it. Confirm **App + Enterprise Access** and **Generate user access tokens**, then re-authorize the app in the Admin Console. Verify `BOX_USER_ID` is the managed user's ID (digits only, no spaces).
The request succeeded, but no workflow matched for this caller. Check each of the following:
* You are authenticated as a **managed user** who can run Automate, not as the enterprise service account. A user token that returns the workflow while the app returns `entries: []` usually means the app still uses `enterprise_id` instead of `user_id`.
* The workflow is **published**, not saved as a draft.
* The workflow has a **Manual Start** trigger.
* The trigger's folder is the folder whose ID you passed as `folder_id`.
* The managed user can access that folder.
Several causes produce a 404 here:
* Box Automate is not enabled for your enterprise. Ask your admin to enable Box Automate.
* Your account is on the Free Developer Plan, where these endpoints are unavailable.
* The `box-version: 2026.0` header is missing.
* You passed the action ID in the URL path. The path takes `entries[].workflow.id`; the body takes `entries[].id`.
The workflow and action IDs can be valid for a different actor. Hardcoding IDs from a successful user-token curl does not help if the app still authenticates as the service account. Switch the client to `BOX_USER_ID`, then confirm that `file_ids` contains at least one ID, at most 20 IDs, and that every file is within the Manual Start folder scope.
The request reached the workflow but the payload was rejected. Confirm that `file_ids` contains at least one ID, that it holds no more than 20 IDs, and that every file is within the folder scope configured on the Manual Start trigger.
The workflow variable is not resolving to your metadata field. Confirm that the field keys in `tag_evidence` match the `fields[].key` values returned by `GET /2.0/metadata_templates/enterprise/:key/schema`, and that the task message references the Claim ID field from that template.
The app is missing the required scope. Enable **Read and write all files and folders stored in Box** in the Developer Console. Depending on your authentication method and enterprise settings, the app requires admin authorization or reauthorization in the Admin Console before a scope change takes effect.
The Automate endpoints are Beta and not yet in `box-sdk-gen`. Re-paste the prompt and emphasize `client.make_request` with `box-version: 2026.0`, or select the **Build by hand** tab in [Build the service](#build-the-service) for the tested modules.
## Scaling to production
The sample calls `GET /2.0/automate_workflows` on every review to resolve the workflow by name. That list call is optional in production. The IDs you need are stable for a given published workflow:
| Value | Source | Used in |
| ----------- | ----------------------- | -------------------------------------------------------- |
| Workflow ID | `entries[].workflow.id` | Path: `POST /2.0/automate_workflows/{workflow_id}/start` |
| Action ID | `entries[].id` | Body: `workflow_action_id` |
Resolve them once at startup, or store them as configuration after a successful list call:
```bash theme={null}
BOX_AUTOMATE_WORKFLOW_ID=
BOX_AUTOMATE_WORKFLOW_ACTION_ID=
```
Then call start with those IDs and skip `find_workflow_action`. Keep the list lookup as a fallback if start begins failing (for example after you replace the workflow in the builder).
Caching IDs only skips the list call. Start still requires a managed user who can run Automate. Hardcoding IDs from a successful user-token curl does not work if the app authenticates as the enterprise service account. That case returns `400 Action not found`, not an empty list.
A double-submitted request starts the workflow twice and can create duplicate approval tasks on the same evidence. Do not rely on `reviewStatus: in_review` alone as a lock: this tutorial sets that value when a review starts and never clears it, so a naive skip would block legitimate resubmits.
Prefer an idempotency check in your claims system (for example, ignore a repeat `claim_id` + `file_ids` start while a review is open), or inspect the file for an incomplete approval task before calling start. If you use metadata as the lock, add an Automate outcome on the approved and rejected branches that updates `reviewStatus` when the decision is done.
`POST /reviews` needs authentication in production. Verify a signed request from your claims system, or place the service behind your existing gateway. Keep credentials in a secret manager rather than a `.env` file, and never expose user or app tokens to a browser client. Prefer a dedicated managed user with the least Automate and folder access your flow needs, rather than a personal admin account.
Tagging metadata before the run is a workaround for a Beta limitation, and it costs one API call per file. When the start endpoint accepts fields at runtime, pass the claim ID directly in the start request and keep metadata only where you want the claim ID to persist on the file for search and reporting. Isolating the workaround in `claims_metadata.py` makes that a single-module change.
A single start request accepts 20 files at most. For larger evidence sets, split the files into batches and start one run per batch (each batch can create its own approval tasks), or restructure the workflow to trigger on the case folder rather than on individual files.
## Next steps
Install skills so your coding agent can scaffold more Box integrations from natural language.
See the full API specification for the manual start endpoint.