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

A set of endpoints used to split a paginated source document into multiple files based on user-defined or AI-generated page ranges.

## Document Split

A standard representation of a Document Split job. The job represents a request to split a paginated source document into multiple files based on either a manual set of page ranges, a non-linear page selection, or a smart prompt-driven analysis.

> [accordion] Attributes and example
>
> | Property | Type | Required | Description |
> | - | - | - | - |
> | `id` | `string` | Yes | The unique identifier for the Document Split job. |
> | `type` | `enum<string>` | Yes | The value will always be `document_split`. Available options: `document_split`. |
> | `source_file` | `File reference` | Yes | The file to split. |
> | `status` | `enum<string>` | Yes | The current state of the Document Split job. Available options: `submitted`, `completed`, `failed`, `completed_with_error`. |
> | `split_input` | `Document Split create request type` | Yes | The caller-supplied input that was used to perform the split. The shape mirrors the request: for a `manual` split, `split_input` contains `split_type` and `split_definition`; for a `page_selection` split, `split_input` contains `split_type` and `page_selection`; for a `smart` split, `split_input` contains `split_type` and the caller-supplied `prompt`. For smart splits, the page ranges that Box produced are exposed under `output.split_definition`. |
> | `output` | [Document Split output](#document-split-output) | No | The result of the Document Split job. `null` until the job has produced output. Can be `null`. |
> | `destination_folder` | `Folder reference` | Yes | The folder that received the generated files. |
> | `input_source` | `enum<string>` | Yes | The system that initiated the request, used for analytics and traceability. Available options: `api`, `box`, `relay`, `salesforce`. |
> | `created_at` | `string` | No | When the Document Split job was created. |
> | `created_by` | `User (Mini)` | No | The user who created the Document Split job. |
> | `enterprise` | `Enterprise reference` | No | The enterprise that owns the Document Split job. |
> | `failures` | [Document Split failures](#document-split-failures) | No | Errors and warnings that occurred during the document split. `null` when no failures were recorded. Can be `null`. |
> | `external_id` | `string` | No | An optional identifier supplied by the caller when the Document Split job was created. Returned for correlation only. It is not a Box resource ID, is not required to be unique, and cannot be used to look up the job. |
>
> ```json Example theme={null}
> {
>   "id": "1748426",
>   "type": "document_split",
>   "source_file": {
>     "type": "file",
>     "id": "42037322"
>   },
>   "status": "submitted",
>   "split_input": {
>     "split_type": "manual",
>     "version": "v_1",
>     "split_definition": [
>       {
>         "start": 1,
>         "end": 5
>       },
>       {
>         "start": 6,
>         "end": 14
>       }
>     ]
>   },
>   "output": {
>     "generated_files": [
>       {
>         "type": "file",
>         "id": "42037322"
>       }
>     ],
>     "split_definition": [
>       {
>         "start": 1,
>         "end": 10
>       },
>       {
>         "start": 11,
>         "end": 25
>       }
>     ]
>   },
>   "destination_folder": {
>     "type": "folder",
>     "id": "42037322"
>   },
>   "input_source": "api",
>   "created_at": "2023-10-26T15:30:00Z",
>   "created_by": {
>     "id": "11446498",
>     "type": "user",
>     "name": "Aaron Levie",
>     "login": "ceo@example.com"
>   },
>   "enterprise": {
>     "id": "1910967",
>     "type": "enterprise"
>   },
>   "failures": {
>     "errors": [
>       "The source file could not be processed."
>     ],
>     "warnings": [
>       "Some pages were skipped because they were blank."
>     ]
>   },
>   "external_id": "invoice-48291"
> }
> ```

## Document Split create request

The request body for creating a Document Split job. The `split_input` property carries the caller-supplied input that determines how the split is performed.

> [accordion] Attributes and example
>
> | Property | Type | Required | Description |
> | - | - | - | - |
> | `source_file_id` | `string` | Yes | The ID of the source file to split. |
> | `destination_folder_id` | `string` | Yes | The ID of the folder where the resulting files will be uploaded. |
> | `input_source` | `enum<string>` | Yes | The system that initiated the request, used for analytics and traceability. Available options: `api`, `box`, `relay`, `salesforce`. |
> | `split_input` | `Document Split create request type` | Yes | |
> | `external_id` | `string` | No | An optional identifier supplied by the caller for this Document Split job. The value is returned on job responses for correlation only. It is not a Box resource ID, is not required to be unique, and cannot be used to look up the job. |
>
> ```json Example theme={null}
> {
>   "source_file_id": "12345",
>   "destination_folder_id": "14047816008",
>   "input_source": "api",
>   "split_input": {
>     "split_type": "manual",
>     "version": "v_1",
>     "split_definition": [
>       {
>         "start": 1,
>         "end": 5
>       },
>       {
>         "start": 6,
>         "end": 14
>       }
>     ]
>   },
>   "external_id": "invoice-48291"
> }
> ```

## Document Split create response

A reference to a newly created Document Split job. Returned when a Document Split job is accepted for asynchronous processing. Clients can poll the full job representation using this ID.

> [accordion] Attributes and example
>
> | Property | Type | Required | Description |
> | - | - | - | - |
> | `type` | `enum<string>` | Yes | The value will always be `document_split`. Available options: `document_split`. |
> | `id` | `string` | Yes | The unique identifier of the created Document Split job. |
>
> ```json Example theme={null}
> {
>   "type": "document_split",
>   "id": "1748426"
> }
> ```

## Document Split failures

Errors and warnings that occurred during a Document Split job.

> [accordion] Attributes and example
>
> | Property | Type | Required | Description |
> | - | - | - | - |
> | `errors` | array of `string` | Yes | A list of errors that occurred during the document job. |
> | `warnings` | array of `string` | Yes | A list of warnings that occurred during the document job. |
>
> ```json Example theme={null}
> {
>   "errors": [
>     "The source file could not be processed."
>   ],
>   "warnings": [
>     "Some pages were skipped because they were blank."
>   ]
> }
> ```

## Document Split output

The set of files produced by a completed Document Split job.

> [accordion] Attributes and example
>
> | Property | Type | Required | Description |
> | - | - | - | - |
> | `generated_files` | array of `File reference` | No | References to the files that were created by the split. |
> | `split_definition` | array of `Document Split page range` | No | The page ranges that Box produced for a `smart` split. Each entry corresponds to one generated file with the inclusive page range `[start, end]`. Omitted or `null` for `manual` splits, where the caller-supplied ranges are available in `split_input.split_definition`. Omitted for `page_selection` splits, where the caller-supplied page layout is available in `split_input.page_selection`. Can be `null`. |
>
> ```json Example theme={null}
> {
>   "generated_files": [
>     {
>       "type": "file",
>       "id": "42037322"
>     }
>   ],
>   "split_definition": [
>     {
>       "start": 1,
>       "end": 10
>     },
>     {
>       "start": 11,
>       "end": 25
>     }
>   ]
> }
> ```

## Document Splits

A paginated list of Document Split jobs.

> [accordion] Attributes and example
>
> | Property | Type | Required | Description |
> | - | - | - | - |
> | `entries` | array of [Document Split](#document-split) | No | A list of Document Split jobs. |
> | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
> | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
>
> ```json Example theme={null}
> {
>   "entries": [
>     {
>       "id": "1748426",
>       "type": "document_split",
>       "source_file": {
>         "type": "file",
>         "id": "42037322"
>       },
>       "status": "submitted",
>       "split_input": {
>         "split_type": "manual",
>         "version": "v_1",
>         "split_definition": [
>           {
>             "start": 1,
>             "end": 5
>           },
>           {
>             "start": 6,
>             "end": 14
>           }
>         ]
>       },
>       "output": {
>         "generated_files": [
>           {
>             "type": "file",
>             "id": "42037322"
>           }
>         ],
>         "split_definition": [
>           {
>             "start": 1,
>             "end": 10
>           },
>           {
>             "start": 11,
>             "end": 25
>           }
>         ]
>       },
>       "destination_folder": {
>         "type": "folder",
>         "id": "42037322"
>       },
>       "input_source": "api",
>       "created_at": "2023-10-26T15:30:00Z",
>       "created_by": {
>         "id": "11446498",
>         "type": "user",
>         "name": "Aaron Levie",
>         "login": "ceo@example.com"
>       },
>       "enterprise": {
>         "id": "1910967",
>         "type": "enterprise"
>       },
>       "failures": {
>         "errors": [
>           "The source file could not be processed."
>         ],
>         "warnings": [
>           "Some pages were skipped because they were blank."
>         ]
>       },
>       "external_id": "invoice-48291"
>     }
>   ],
>   "limit": 1000,
>   "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
> }
> ```