How to split a document bundle
Split divides a bundle of pages into separate documents. Use it when one file holds several documents, such as a scanned stack of invoices and receipts.
Quick start
Split takes the same document input, plus a config describing how to split. Split always lets the model find where one document ends and the next begins. The result lists the child documents, each with its original page numbers and a document_ref you can reuse in other requests.
Send the options as a JSON string in request. Split and Classify read their options from a request form field next to the file. In Python the SDK takes it as a dict (request={...}); with cURL, pass the JSON text. In Python, file takes a list and job_id is passed by name, get_status(job_id=...). In JavaScript, file takes an array, job_id is positional, getStatus(job_id), and request and response fields use the wire names (classify_segments, review_required), as for Parse and Extract.
Split options
Split always lets the model find where each document starts and ends — there is no method.
config.classify_segments:true(classify each document, the default) orfalse(split only). Withfalse, omitcategories.config.categories: optional, up to 200 entries, each with atypeand optionaldescription. Addidentifier_key(plain words such as"invoice number") to fill each document’sidentifier.config.instructions: optional instructions, up to 8,000 characters.config.page_ranges: the pages to split — a string such as"1-3,5"or a list of{start, end}. Omitted: every page.config.constraints.must_keep_together/must_split_before: force page runs into one document, or force a page to start a new one.config.review_policy.min_segment_confidence/min_class_confidence: 0–1, default0.9.
Split does not accept quality, output, budget, routing_profile, method, pages_per_segment, remainder, segment_ranges, split_on, identifier_fields, execution or wait_ms.
Split results
- Each segment is a child document.
pagesrefers to its original page numbers, anddocument_reflets you reuse it in another request. - With
classify_segments: true,typeis the matching category andclassification_statusismatched, orunknownwithunknown_reason: "no_matching_type"when none fits. status: "completed"means processing finished, not that every segment passed review. Checkreview_requiredon each segment before accepting the result automatically.
Request behaviours
Split and Classify share these request behaviours:
- Inputs: PDF, PNG, JPEG, or TIFF. Repeat the
filefield for up to 10 documents with the same config; you get a parent job and adocumentslist of individual jobs, each with its ownstatus_urlandresults_url. The parent’s results include each document’s result underdocuments. You can also upload first withPOST /doc-ai/v1/job/uploadand send the id asupload_ids. URL input is not available. - Retries: add an
Idempotency-Keyheader to retry the same submission without creating another job. A changed request under the same key returns409. - Capabilities:
GET /doc-ai/v1/capabilitieslists the operations, input formats, split options, and limits enabled on your deployment.