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

# Create Document Split job

> Initiates a Document Split job for the supplied source file. The job runs asynchronously; clients can poll the returned job ID to track progress.

All split-specific input lives under `split_input`. When `split_input.split_type` is `manual`, provide `split_input.split_definition` (continuous page ranges; `version` may be omitted or `v_1`). When `split_input.split_type` is `page_selection`, provide `split_input.page_selection` (non-linear page segments; `version` may be omitted or `v_2`). `split_input.prompt` must not be provided for either of those variants. When `split_input.split_type` is `smart`, `split_input.prompt` is required and neither `split_input.split_definition` nor `split_input.page_selection` must be provided.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


## OpenAPI

````yaml box-openapi-v2026.0.json POST /document_splits
openapi: 3.0.2
info:
  title: Box Platform API
  description: >-
    [Box Platform](https://developer.box.com) provides functionality to provide
    access to content stored within [Box](https://box.com). It provides
    endpoints for basic manipulation of files and folders, management of users
    within an enterprise, as well as more complex topics such as legal holds and
    retention policies.
  termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9
  contact:
    name: Box, Inc
    url: https://developer.box.com
    email: devrel@box.com
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '2026.0'
  x-box-commit-hash: 53bdced3cd
servers:
  - url: https://api.box.com/2.0
    description: Box Platform API server.
security:
  - OAuth2Security: []
tags:
  - name: Automate Workflows
    description: Endpoints for listing and manually starting Automate workflow actions.
    x-box-tag: automate_workflows
  - name: Convert to Box Note
    description: Create Box Notes from supported source content (for example Markdown).
    x-box-tag: notes
  - name: Document Split
    description: >-
      A set of endpoints used to split a paginated source document into multiple
      files based on user-defined or AI-generated page ranges.
    x-box-tag: document_split
  - name: Query
    description: Query for your items.
    x-box-tag: query
externalDocs:
  description: Box Developer Documentation.
  url: https://developer.box.com
paths:
  /document_splits:
    post:
      tags:
        - Document Split
      summary: Create Document Split job
      description: >-
        Initiates a Document Split job for the supplied source file. The job
        runs asynchronously; clients can poll the returned job ID to track
        progress.


        All split-specific input lives under `split_input`. When
        `split_input.split_type` is `manual`, provide
        `split_input.split_definition` (continuous page ranges; `version` may be
        omitted or `v_1`). When `split_input.split_type` is `page_selection`,
        provide `split_input.page_selection` (non-linear page segments;
        `version` may be omitted or `v_2`). `split_input.prompt` must not be
        provided for either of those variants. When `split_input.split_type` is
        `smart`, `split_input.prompt` is required and neither
        `split_input.split_definition` nor `split_input.page_selection` must be
        provided.
      operationId: post_document_splits_v2026.0
      parameters:
        - $ref: '#/components/parameters/BoxVersionHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentSplitCreateRequest'
            examples:
              manual:
                summary: Manual split request
                value:
                  source_file_id: '12345'
                  destination_folder_id: '14047816008'
                  input_source: api
                  split_input:
                    split_type: manual
                    split_definition:
                      - start: 1
                        end: 5
                      - start: 6
                        end: 14
              page_selection:
                summary: Page selection split request
                value:
                  source_file_id: '12345'
                  destination_folder_id: '14047816008'
                  input_source: api
                  split_input:
                    split_type: page_selection
                    version: v_2
                    page_selection:
                      - name: exhibits
                        segments:
                          - type: single_page
                            page: 4
                          - type: single_page
                            page: 8
                          - type: single_page
                            page: 12
                      - name: signatures
                        segments:
                          - type: page_range
                            start: 6
                            end: 8
                          - type: single_page
                            page: 15
              smart:
                summary: Smart split request
                value:
                  source_file_id: '12345'
                  destination_folder_id: '14047816008'
                  input_source: api
                  split_input:
                    split_type: smart
                    prompt: Split this contract into one file per signed section.
      responses:
        '202':
          description: >-
            The Document Split job was accepted for processing. Returns a
            reference to the newly created job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentSplitCreateResponse'
        '400':
          description: >-
            Returned when the request body is malformed or required fields are
            missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '401':
          description: >-
            Returned when the access token provided in the `Authorization`
            header is not recognized or not provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: >-
            Returned when the authenticated user does not have access to the
            Document Generation feature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: >-
            Returned when the source file or destination folder cannot be found
            or the user does not have access to it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '429':
          description: >-
            Returned when the user has sent too many requests in a given amount
            of time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  parameters:
    BoxVersionHeader:
      name: box-version
      in: header
      description: Version header.
      allowEmptyValue: false
      required: true
      schema:
        type: string
        enum:
          - '2026.0'
      example: '2026.0'
  schemas:
    DocumentSplitCreateRequest:
      description: >-
        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.
      type: object
      properties:
        source_file_id:
          description: The ID of the source file to split.
          type: string
          example: '12345'
        destination_folder_id:
          description: The ID of the folder where the resulting files will be uploaded.
          type: string
          example: '14047816008'
        input_source:
          description: >-
            The system that initiated the request, used for analytics and
            traceability.
          type: string
          example: api
          enum:
            - api
            - box
            - relay
            - salesforce
        split_input:
          $ref: '#/components/schemas/DocumentSplitCreateRequestType'
        external_id:
          description: >-
            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.
          type: string
          example: invoice-48291
          maxLength: 255
      required:
        - source_file_id
        - destination_folder_id
        - input_source
        - split_input
      title: Document Split create request
      x-box-resource-id: document_split_create_request_v2026.0
      x-box-tag: document_split
    DocumentSplitCreateResponse:
      description: >-
        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.
      type: object
      properties:
        type:
          description: The value will always be `document_split`.
          type: string
          example: document_split
          enum:
            - document_split
        id:
          description: The unique identifier of the created Document Split job.
          type: string
          example: '1748426'
      required:
        - type
        - id
      title: Document Split create response
      x-box-resource-id: document_split_create_response_v2026.0
      x-box-tag: document_split
    ClientError:
      description: A generic error.
      type: object
      properties:
        type:
          description: The value will always be `error`.
          type: string
          example: error
          enum:
            - error
          nullable: false
        status:
          description: The HTTP status of the response.
          type: integer
          format: int32
          example: 400
          nullable: false
        code:
          description: A Box-specific error code.
          type: string
          example: item_name_invalid
          enum:
            - created
            - accepted
            - no_content
            - redirect
            - not_modified
            - bad_request
            - unauthorized
            - forbidden
            - not_found
            - method_not_allowed
            - conflict
            - precondition_failed
            - too_many_requests
            - internal_server_error
            - unavailable
            - item_name_invalid
            - insufficient_scope
        message:
          description: A short message describing the error.
          type: string
          example: Method Not Allowed
          nullable: false
        context_info:
          description: >-
            A free-form object that contains additional context about the error.
            The possible fields are defined on a per-endpoint basis. `message`
            is only one example.
          type: object
          example:
            message: Something went wrong
          additionalProperties: {}
          nullable: true
        help_url:
          description: A URL that links to more information about why this error occurred.
          type: string
          example: >-
            https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
          nullable: false
        request_id:
          description: >-
            A unique identifier for this response, which can be used when
            contacting Box support.
          type: string
          example: abcdef123456
          nullable: false
      title: Client error
      x-box-resource-id: client_error_v2026.0
    DocumentSplitCreateRequestType:
      description: Validation rules for the supported Document Split create request types.
      oneOf:
        - $ref: '#/components/schemas/DocumentSplitCreateRequestManual'
        - $ref: '#/components/schemas/DocumentSplitCreateRequestPageSelection'
        - $ref: '#/components/schemas/DocumentSplitCreateRequestSmart'
      title: Document Split create request type
      x-box-tag: document_split
    DocumentSplitCreateRequestManual:
      description: >-
        Validation rules for creating a Document Split job using caller-supplied
        page ranges.
      type: object
      properties:
        split_type:
          description: Discriminator. Must be `manual` for this variant.
          type: string
          example: manual
          enum:
            - manual
        version:
          description: >-
            The version of the manual split input format. Omitted or `v_1` is
            the legacy `split_definition` format. Existing clients may omit this
            field.
          type: string
          example: v_1
          enum:
            - v_1
        split_definition:
          description: >-
            Page ranges that define the split. Each entry produces one output
            file containing the inclusive page range `[start, end]`.
          type: array
          items:
            $ref: '#/components/schemas/DocumentSplitPageRange'
          example:
            - start: 1
              end: 5
            - start: 6
              end: 14
          minItems: 1
      not:
        anyOf:
          - required:
              - prompt
          - required:
              - page_selection
      required:
        - split_type
        - split_definition
      title: Document Split manual create request
      x-box-tag: document_split
    DocumentSplitCreateRequestPageSelection:
      description: >-
        Validation rules for creating a Document Split job using non-linear page
        selections. Each item produces one output file from the declared page
        segments.
      type: object
      properties:
        split_type:
          description: Discriminator. Must be `page_selection` for this variant.
          type: string
          example: page_selection
          enum:
            - page_selection
        version:
          description: >-
            The version of the page selection input format. Optional. When
            provided must be `v_2`.
          type: string
          example: v_2
          enum:
            - v_2
        page_selection:
          $ref: '#/components/schemas/DocumentSplitPageSelection'
      not:
        anyOf:
          - required:
              - prompt
          - required:
              - split_definition
      required:
        - split_type
        - page_selection
      title: Document Split page selection create request
      x-box-tag: document_split
    DocumentSplitCreateRequestSmart:
      description: >-
        Validation rules for creating a Document Split job using Box-generated
        page ranges guided by a caller-supplied prompt.
      type: object
      properties:
        split_type:
          description: Discriminator. Must be `smart` for this variant.
          type: string
          example: smart
          enum:
            - smart
        prompt:
          description: >-
            A natural language prompt that guides automatic page range
            detection.
          type: string
          example: Split this contract into one file per signed section.
          minLength: 1
      not:
        anyOf:
          - required:
              - split_definition
          - required:
              - page_selection
      required:
        - split_type
        - prompt
      title: Document Split smart create request
      x-box-tag: document_split
    DocumentSplitPageRange:
      description: >-
        An inclusive page range used to define one slice of a manual Document
        Split job.
      type: object
      properties:
        start:
          description: The first page (inclusive) included in this slice.
          type: integer
          format: int32
          example: 1
          minimum: 1
        end:
          description: The last page (inclusive) included in this slice.
          type: integer
          format: int32
          example: 10
          minimum: 1
      additionalProperties: false
      required:
        - start
        - end
      title: Document Split page range
      x-box-tag: document_split
    DocumentSplitPageSelection:
      description: >-
        Defines a non-sequential page selection for a Document Split job. Each
        item in the array produces one output PDF assembled from the declared
        page segments.
      type: array
      items:
        $ref: '#/components/schemas/DocumentSplitPageSelectionItem'
      example:
        - name: exhibits
          segments:
            - type: single_page
              page: 4
            - type: single_page
              page: 8
            - type: page_range
              start: 6
              end: 8
      minItems: 1
      title: Document Split page selection
      x-box-tag: document_split
    DocumentSplitPageSelectionItem:
      description: >-
        A single output file definition within a page selection request. Each
        item produces one PDF containing the pages specified by its segments
        array.
      type: object
      properties:
        name:
          description: >-
            Optional name for the output file (without extension). When omitted
            the system generates a sequential name based on the source file
            name.
          type: string
          example: exhibits
          minLength: 1
        segments:
          description: >-
            An ordered list of page segments to include in this output file.
            Each segment specifies either a single page or a contiguous page
            range.
          type: array
          items:
            $ref: '#/components/schemas/DocumentSplitPageSelectionSegment'
          example:
            - type: single_page
              page: 4
            - type: page_range
              start: 6
              end: 8
          minItems: 1
      required:
        - segments
      title: Document Split page selection item
      x-box-tag: document_split
    DocumentSplitPageSelectionSegment:
      description: >-
        A single page segment within a page selection item. The `type` field
        identifies whether the segment is a single page or an inclusive page
        range.
      oneOf:
        - $ref: '#/components/schemas/DocumentSplitPageSelectionSinglePage'
        - $ref: '#/components/schemas/DocumentSplitPageSelectionPageRange'
      title: Document Split page selection segment
      x-box-tag: document_split
    DocumentSplitPageSelectionSinglePage:
      description: >-
        A page selection segment that includes a single page from the source
        document.
      type: object
      properties:
        type:
          description: Discriminator. Must be `single_page` for this variant.
          type: string
          example: single_page
          enum:
            - single_page
        page:
          description: A single page number to include.
          type: integer
          format: int32
          example: 4
          minimum: 1
      additionalProperties: false
      required:
        - type
        - page
      title: Document Split page selection single page
      x-box-tag: document_split
    DocumentSplitPageSelectionPageRange:
      description: >-
        A page selection segment that includes an inclusive page range from the
        source document.
      type: object
      properties:
        type:
          description: Discriminator. Must be `page_range` for this variant.
          type: string
          example: page_range
          enum:
            - page_range
        start:
          description: The first page (inclusive) included in this segment.
          type: integer
          format: int32
          example: 6
          minimum: 1
        end:
          description: The last page (inclusive) included in this segment.
          type: integer
          format: int32
          example: 8
          minimum: 1
      additionalProperties: false
      required:
        - type
        - start
        - end
      title: Document Split page selection page range
      x-box-tag: document_split
  securitySchemes:
    OAuth2Security:
      type: oauth2
      description: >-
        The access token received from the authorization server in the OAuth 2.0
        flow.
      flows:
        authorizationCode:
          authorizationUrl: https://account.box.com/api/oauth2/authorize
          tokenUrl: https://api.box.com/oauth2/token
          scopes:
            root_readonly: Read all files and folders stored in Box
            root_readwrite: Read and write all files and folders stored in Box
            manage_app_users: Provision and manage app users
            manage_managed_users: Provision and manage managed users
            manage_groups: Manage an enterprise's groups
            manage_webhook: Create webhooks programmatically through the API
            manage_enterprise_properties: Manage enterprise properties
            manage_data_retention: Manage data retention polices
            manage_legal_hold: Manage Legal Holds

````