> ## 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.

# Document Split

> Use the Box API to break a multi-page PDF stored in Box into smaller sub-documents and save the results to a Box folder.

export const MultiRelatedLinks = ({sections = []}) => {
  if (!sections || sections.length === 0) {
    return null;
  }
  return <div className="space-y-8">
      {sections.map((section, index) => <RelatedLinks key={index} title={section.title} items={section.items} />)}
    </div>;
};

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 <div className="my-8">
      {}
      <h3 className="text-sm font-bold uppercase tracking-wider mb-4">{title}</h3>

      {}
      <div className="flex flex-col gap-3">
        {items.map((item, index) => <a key={index} href={item.href} className="py-2 px-3 rounded related_link hover:bg-[#f2f2f2] dark:hover:bg-[#111827] flex items-center gap-3 group no-underline hover:no-underline border-b-0">
            {}
            <span className={`px-2 py-1 rounded-full text-xs font-semibold uppercase tracking-wide flex-shrink-0 ${getBadgeClass(item.badge)}`}>
              {item.badge}
            </span>

            {}
            <span className="text-base">{item.label}</span>
          </a>)}
      </div>
    </div>;
};

export const Link = ({href, children, className, ...props}) => {
  const localizedHref = localizeLink(href);
  return <a href={localizedHref} className={className} {...props}>
      {children}
    </a>;
};

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 <Link href="/guides/docgen/manual-split">manual split</Link>.
* Let Box interpret natural language instructions to determine how pages are grouped, using a <Link href="/guides/docgen/smart-split">smart split</Link>.

## 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 <Link href="/guides/docgen/docgen-getting-started">get started with Box Doc Gen</Link> 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 <Link href="/guides/api-calls/api-versioning-strategy">Box API versioning</Link>.

## Split types

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

| Split type                                               | Best for                                 | You provide                                       |
| -------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------- |
| <Link href="/guides/docgen/manual-split">`manual`</Link> | Known page ranges                        | A `split_definition` array of start and end pages |
| <Link href="/guides/docgen/smart-split">`smart`</Link>   | Content-based or marker-based boundaries | A natural language `prompt`                       |

<Tip>
  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.
</Tip>

<Note>
  A smart split consumes AI Units. Box consumes 1 AI Unit for every 4 pages processed.
</Note>

## How Document Split works

Document Split runs asynchronously in two steps:

1. Send a `POST` request to `/2.0/document_splits` to create a split job. The response contains a job ID.
2. 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 <Link href="/guides/docgen/manual-split">manual split</Link> or <Link href="/guides/docgen/smart-split">smart split</Link> guide.

The response contains the ID of the split job:

```json theme={null}
{
  "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.

```sh cURL theme={null}
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.

```json theme={null}
{
  "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.

<RelatedLinks
  title="RELATED GUIDES"
  items={[
{ label: translate("Manual split"), href: "/guides/docgen/manual-split", badge: "GUIDE" },
{ label: translate("Smart split"), href: "/guides/docgen/smart-split", badge: "GUIDE" },
{ label: translate("Get started with Box Doc Gen"), href: "/guides/docgen/docgen-getting-started", badge: "GUIDE" }
]}
/>