> ## 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 title="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"
  }
  ```
</Accordion>

## 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 title="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"
  }
  ```
</Accordion>

## 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 title="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"
  }
  ```
</Accordion>

## Document Split failures

Errors and warnings that occurred during a Document Split job.

<Accordion title="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."
    ]
  }
  ```
</Accordion>

## Document Split output

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

<Accordion title="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
      }
    ]
  }
  ```
</Accordion>

## Document Splits

A paginated list of Document Split jobs.

<Accordion title="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"
  }
  ```
</Accordion>