Document Split

💡 API calls require authentication. Refer to Interface Authentication for authentication

POST {apiPrefix}/split

Submit document split task

If task addition fails, the failure reason is returned synchronously
If task addition succeeds, the task ID is returned synchronously. Third parties can configure task callback notifications to get task status.

Text Document Split

Supports splitting text documents (doc, docx, wps) by heading, section break, or keyword.

Request Body:

Content-Type is application/json

Parameter Name	Type	Description	Required
fileUrl	string	File download link	Yes
filename	string	Filename with extension (supports text (doc,docx,wps))	Yes
tokenType	string	Third-party token type, value is cookie or header	No
tokenValue	string	Third-party token value, passed back when zOffice downloads files or callback notifications	No
callback	string	Callback address. zOffice will callback to notify status after task completion	Yes
type	string	Split type, enum: WORDHEADING: split by heading, SECTBREAK: split by section break, TEXT: split by keyword	Yes
keyword	string	Required when type is TEXT, split document by this text (this keyword refers to text in headings, headings containing it regardless of level)	No

For tokenType/tokenValue/callback description, see Common Field Description in this document
Text file size cannot exceed 300m.

Request Example:

{
    "fileUrl": "https://example.com/files/document.docx",
    "filename": "document.docx",
    "callback": "https://example.com/callback",
    "type": "WORDHEADING"
}

Normal Response:

{
    "taskId": "6f6598c8-c87e-420b-b6c4-6f1b187201dc",
    "code": "Ok",
    "detail": {
        "taskStatus": "IN_QUEUE"
    }
}

Error Response:

{
    "taskId": "695fbf6e-90d2-42ba-83d5-00e81e5e366e",
    "code": "TaskQueueCongestion",
    "detail": {
        "taskStatus": "FAIL"
    }
}

PDF Split

Supported since v8.3

Supports PDF file splitting with three split modes, splitting a PDF file into multiple PDF files.

Request Body:

Content-Type is application/json

Parameter Name	Type	Description	Required
fileUrl	string	File download link	Yes
filename	string	Filename with extension (only supports pdf)	Yes
tokenType	string	Third-party token type, value is cookie or header	No
tokenValue	string	Third-party token value, passed back when zOffice downloads files or callback notifications	No
callback	string	Callback address. zOffice will callback to notify status after task completion	Yes
type	string	Split mode, enum: PAGERANGE / FIXEDPAGES / FILECOUNT	Yes
ranges	string	Page ranges, required when type is PAGERANGE	Conditional
fixedPages	number	Fixed number of pages per file, required when type is FIXEDPAGES. Positive integer, minimum 1	Conditional
fileCount	number	Number of files to split into, required when type is FILECOUNT. Integer, range 2~50	Conditional
output	string	Output mode: singleFile / array. Default is array. Only effective when type is PAGERANGE	No

For tokenType/tokenValue/callback description, see Common Field Description in this document
PDF file size cannot exceed 200m.
The maximum number of split output files cannot exceed 50.

Split Mode Description

type Value	Description
PAGERANGE	Split by page ranges. Requires ranges parameter, each range produces one sub-PDF file (max 50 segments in ranges). Supports output parameter to control output mode
FIXEDPAGES	Split by fixed page count. Requires fixedPages parameter, each file contains a fixed number of pages (remaining pages at the end form the last file). Output files cannot exceed 50
FILECOUNT	Split evenly by file count. Requires fileCount parameter (max 50), divides the PDF into the specified number of files (when pages don't divide evenly, earlier files get one extra page)

ranges Parameter Format

ranges is a string with multiple segments separated by commas. Each segment can be a single page number or a start-end range connected by a hyphen.

Format: page_or_range,page_or_range,...
Pages start from 1, start page must be less than or equal to end page
Single page: 3 extracts only page 3
Page range: 1-5 extracts pages 1 through 5
Mixed usage: 1-3,5,7-10 splits into three files (pages 1-3, page 5, pages 7-10)
Page ranges are allowed to overlap, e.g. 1-5,3-8 produces two sub-PDFs (containing pages 1-5 and pages 3-8 respectively)

output Parameter Description

output Value	Description
array	Default. Each ranges segment is split into an independent file, download result is a ZIP archive
singleFile	Merges all page ranges specified by ranges into a single PDF output. Only effective when type is PAGERANGE, ignored for other split modes

Request Examples

Example 1: Split by page ranges into multiple files (PAGERANGE)

{
    "fileUrl": "https://example.com/files/document.pdf",
    "filename": "document.pdf",
    "callback": "https://example.com/callback",
    "type": "PAGERANGE",
    "ranges": "1-3,4-6,7-10"
}

Example 2: Extract specified pages merged into single file (output=singleFile)

{
    "fileUrl": "https://example.com/files/document.pdf",
    "filename": "document.pdf",
    "callback": "https://example.com/callback",
    "type": "PAGERANGE",
    "ranges": "1-3,7-10",
    "output": "singleFile"
}

Example 3: Extract single page (PAGERANGE single page format)

{
    "fileUrl": "https://example.com/files/document.pdf",
    "filename": "document.pdf",
    "callback": "https://example.com/callback",
    "type": "PAGERANGE",
    "ranges": "3"
}

Example 4: Split by fixed pages (FIXEDPAGES), 3 pages per file

{
    "fileUrl": "https://example.com/files/document.pdf",
    "filename": "document.pdf",
    "callback": "https://example.com/callback",
    "type": "FIXEDPAGES",
    "fixedPages": 3
}

Example 5: Split evenly by file count (FILECOUNT), split into 4 files

{
    "fileUrl": "https://example.com/files/document.pdf",
    "filename": "document.pdf",
    "callback": "https://example.com/callback",
    "type": "FILECOUNT",
    "fileCount": 4
}

Normal Response:

{
    "taskId": "6f6598c8-c87e-420b-b6c4-6f1b187201dc",
    "code": "Ok",
    "detail": {
        "taskStatus": "IN_QUEUE"
    }
}

Error Response:

{
    "taskId": "695fbf6e-90d2-42ba-83d5-00e81e5e366e",
    "code": "TaskQueueCongestion",
    "detail": {
        "taskStatus": "FAIL"
    }
}

Error Codes

Error Code	HTTP Status	Description
PdfSplitInvalidType	412	Invalid type parameter, not a valid split mode enum (PAGERANGE/FIXEDPAGES/FILECOUNT)
PdfSplitRangesRequired	412	ranges parameter is missing when type is PAGERANGE
PdfSplitInvalidRangesFormat	412	Invalid ranges format, expected comma-separated page numbers or ranges (e.g. `1-5,10,12-15`)
PdfSplitInvalidFixedPages	412	Invalid fixedPages, must be a positive integer (>= 1)
PdfSplitInvalidFileCount	412	Invalid fileCount, must be an integer >= 2
PdfSplitInvalidOutputValue	412	Invalid output value, only supports singleFile or array

Callback Notification

After the split task is completed, zOffice will notify the task result through the callback address.

Success Notification (output=array, default mode):

{
    "taskId": "1c1cf10b-d9e6-4927-b75e-dddf6b441445",
    "code": "TaskSuccessNotify",
    "detail": {
        "taskStatus": "SUCCESS",
        "defaultDownloadPath": "/docs/publicapi/v1/download",
        "contentId": "640eeac02a9baf5dbc69d426",
        "filename": "document_split.zip"
    }
}

Success Notification (output=singleFile mode):

{
    "taskId": "1c1cf10b-d9e6-4927-b75e-dddf6b441445",
    "code": "TaskSuccessNotify",
    "detail": {
        "taskStatus": "SUCCESS",
        "defaultDownloadPath": "/docs/publicapi/v1/download",
        "contentId": "640eeac02a9baf5dbc69d426",
        "filename": "document_split.pdf"
    }
}

Failure Notification:

{
    "taskId": "1c1cf10b-d9e6-4927-b75e-dddf6b441445",
    "code": "TaskFailNotify",
    "detail": {
        "taskStatus": "FAIL",
        "msg": "split failed"
    }
}

Note

When output is array (default), the downloaded result file after successful splitting is a ZIP archive containing the split PDF files. Sub-files are named in the format {original_filename}_{sequence}.pdf (e.g. document_001.pdf, document_002.pdf).
When output is singleFile (PAGERANGE mode only), the download result is a single PDF file containing all pages specified by ranges.

Text Document Split​

PDF Split​

Split Mode Description​

ranges Parameter Format​

output Parameter Description​

Request Examples​

Error Codes​

Callback Notification​