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

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

Document Split

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.

POST

document_splits

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

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

Learn more about Box SDK versioning strategy.

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

box-version

enum<string>

required

Version header.

Available options:

2026.0

Body

application/json

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.

source_file_id

string

required

The ID of the source file to split.

Example:

"12345"

destination_folder_id

string

required

The ID of the folder where the resulting files will be uploaded.

Example:

"14047816008"

input_source

enum<string>

required

The system that initiated the request, used for analytics and traceability.

Available options:

api,

box,

relay,

salesforce

Example:

"api"

split_input

Document Split manual create request · object

required

Validation rules for creating a Document Split job using caller-supplied page ranges.

Document Split manual create request
Document Split page selection create request
Document Split smart create request

Show child attributes

external_id

string

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.

Maximum string length: 255

Example:

"invoice-48291"

Response

The Document Split job was accepted for processing. Returns a reference to the newly created job.

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

enum<string>

required

The value will always be document_split.

Available options:

document_split

Example:

"document_split"

string

required

The unique identifier of the created Document Split job.

Example:

"1748426"

Last modified on October 19, 2026

API reference

v2025.0

v2026.0

Create Document Split job

Authorizations

Headers

Body

Response