Document Split

Document Split breaks a multi-page PDF stored in Box into smaller sub-documents and saves the results to a Box folder. Use Document Split when you need to:

Break a multi-page PDF into page-range segments you define yourself, using a .
Let Box interpret natural language instructions to determine how pages are grouped, using a .

Example use cases

Team	Example
Sales	Split multi-deal packets into individual quotes
Legal	Isolate signatures and ID proofs from contract packages
Finance	Extract invoices from a multi-invoice PDF
Operations	Split scan batches at QR code separators
HR	Separate onboarding packet sections

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.

API version

All requests to Document Split endpoints must specify a valid API version by setting the box-version header to 2026.0. For more details, see .

Split types

The split_type you send determines the rest of the request body.

Split type	Best for	You provide
	Known page ranges	A `split_definition` array of start and end pages
	Content-based or marker-based boundaries	A natural language `prompt`

Use manual when the page numbers are known, because the results are deterministic. Use smart when the boundaries are easier to describe than to calculate.

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

How Document Split works

Document Split runs asynchronously in two steps:

Send a POST request to /2.0/document_splits to create a split job. The response contains a job ID.
Send a GET request to /2.0/document_splits/{document_split_id} with that ID to retrieve the status and the generated files.

Create a split job

The request body has the same shape for both split types. Only the contents of split_input differ.

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
`input_source`	The source of the input. Use `api` for all API-based requests
`split_input.split_type`	Either `manual` or `smart`
`split_input.split_definition`	The page ranges for a manual split
`split_input.prompt`	The natural language prompt for a smart split

For a complete request example, see the or guide. The response contains the ID of the split job:

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

Get the status and results of a split job

Use the job ID from the POST response to retrieve the details of the split.

cURL

curl -L 'https://api.box.com/2.0/document_splits/128445' \
     -H 'box-version: 2026.0' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>'

The response lists the generated files, the split definition Box applied, the destination folder, and other details of the request.

{
  "output": {
    "generated_files": [
      { "id": "2404332574822", "type": "file" },
      { "id": "2404326035290", "type": "file" }
    ],
    "split_definition": [
      { "start": 1, "end": 5 },
      { "start": 7, "end": 9 }
    ]
  },
  "destination_folder": {
    "id": "408521968626",
    "type": "folder"
  },
  "created_by": {
    "id": "36302517035",
    "type": "user"
  },
  "enterprise": {
    "id": "1217301449",
    "type": "enterprise"
  }
}

For a smart split, the split_definition in the response shows the ranges Box derived from your prompt. Use it to confirm that 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

Example use cases

Prerequisites

API version

Split types

How Document Split works

Create a split job

Get the status and results of a split job

​Example use cases

​Prerequisites

​API version

​Split types

​How Document Split works

​Create a split job

​Get the status and results of a split job

Example use cases

Prerequisites

API version

Split types

How Document Split works

Create a split job

Get the status and results of a split job