Smart split

When split_type is smart, Document Split uses your prompt to decide how to group and split pages into output documents. Clear, specific prompts produce more reliable splits.

A smart split consumes AI Units. Box consumes 1 AI Unit for every 4 pages processed.

Prerequisites

Before you start, follow the steps in the guide to create a platform app and generate an access token. You also need:

A source PDF already stored in Box.
A destination folder in Box that your app can write to.
A prompt that describes how to group the pages.

What you configure

Parameter	Description
`source_file_id`	The Box file ID of the PDF to split
`destination_folder_id`	The Box folder ID where Box stores the output documents
`split_input.split_type`	`smart`
`split_input.prompt`	A natural language prompt that tells Box how to analyze the source PDF and identify the splits

Prompt guidelines

State that the Box file you supply is the source document.
Describe the splitting rule, such as a page count, a marker like a QR code, or a content criterion.
Prefer sequential ranges when order matters, such as contract exhibits followed by signature pages.
Call out the pages or sections to include, and where it helps, the ones to skip.
Avoid ambiguous language such as “split somehow” or “use whatever makes sense.”

Example prompts

Explicit page groups

Split a file into two documents whose ranges you describe in natural language.

Use this document as the source, and split the documents into 2 parts. Pages 1-3 should be the first document, and pages 5-8 should be the second document.

This produces two outputs, corresponding to pages 1 to 3 and pages 5 to 8.

If you already know the exact ranges, use split_type: "manual" with a split_definition instead. See for deterministic results.

QR code as a break point

Treat each QR code page as a separator between documents. Pages before a QR code form one split, and the QR code page itself is excluded unless you specify otherwise.

Use this document as the source. Identify individual pages that contain a QR code, and use each QR code page as a breaking point between document splits. Build the split definition so that if a QR code appears on page 5, pages 1-4 are the first document. If the next QR code appears on page 11, pages 6-10 are the second document. Continue this pattern through the rest of the file.

This produces sequential ranges bounded by the marker pages. With markers on pages 5 and 11, the outputs cover pages 1 to 4 and pages 6 to 10.

Content-based contractual pages

Keep only the pages with substantive contractual content, such as ID proofs, signatures, and executed terms, and skip the boilerplate terms and conditions. Split the retained sections sequentially.

Use this document as the source. Identify all pages that contain real contractual details, such as ID proofs of the signers, signatures of the signers, and other executed contractual details. Skip pages that only contain terms and conditions. Split the retained sections sequentially. For example, if ID proofs are on pages 1-3 and executed signatures are on pages 4-6, produce two documents: pages 1-3 and pages 4-6.

This produces one output for each contiguous block of content that matches the criteria, such as pages 1 to 3 and pages 4 to 6.

Create a smart split job

cURL

curl -L 'https://api.box.com/2.0/document_splits' \
     -H 'Accept: application/json; version=1' \
     -H 'box-version: 2026.0' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -d '{
       "source_file_id": "2390226613215",
       "destination_folder_id": "406457672606",
       "input_source": "api",
       "split_input": {
         "split_type": "smart",
         "prompt": "Identify pages with QR codes in the source file, use each one as a breaking point, and split the document. For example, if there is a QR code on page 5, followed by a QR code on page 11, followed by a QR code on page 18, the result is 2 split documents. The first covers pages 5 to 11 and the second covers pages 12 to 18."
       }
     }'

The response contains the ID of the split job:

{
  "id": "11678",
  "type": "document_split"
}

Use this ID to . The split_definition in that response shows the ranges Box derived from your prompt, so you can confirm the prompt produced the grouping you expected.

Getting started

Applications & integrations

Identity & access

Using the API

Troubleshooting

Content

Collaboration

Metadata & search

Events & webhooks

Users

Intelligent workflow

E-signatures

Security & compliance

Prerequisites

What you configure

Prompt guidelines

Example prompts

Explicit page groups

QR code as a break point

Content-based contractual pages

Create a smart split job

​Prerequisites

​What you configure

​Prompt guidelines

​Example prompts

​Explicit page groups

​QR code as a break point

​Content-based contractual pages

​Create a smart split job

Prerequisites

What you configure

Prompt guidelines

Example prompts

Explicit page groups

QR code as a break point

Content-based contractual pages

Create a smart split job