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.

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

Example

{
  "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.

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.

Example

{
  "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.

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.

Example

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

Document Split failures

Errors and warnings that occurred during a Document Split job.

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.

Example

{
  "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.

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

Example

{
  "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.

Attributes and example

Property	Type	Required	Description
`entries`	array of 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`.

Example

{
  "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"
}

API reference

v2025.0

v2026.0

Document Split resources

Document Split

Document Split create request

Document Split create response

Document Split failures

Document Split output

Document Splits

​Document Split

​Document Split create request

​Document Split create response

​Document Split failures

​Document Split output

​Document Splits

Document Split

Document Split create request

Document Split create response

Document Split failures

Document Split output

Document Splits