This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/dotnet/csharp/extraction/split-document.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. Split documents in C# | Nutrient .NET SDK

A merged PDF can contain several documents, such as invoices, contracts, and identity forms. Use Vision.Split to find where each document starts and return its page range for routing or further processing.

This operation predicts document boundaries and returns JSON. It doesn’t write separate PDF files or modify the source document. Use the returned ranges with your page-extraction workflow when you need individual files.

Download sample

Prerequisites

  • .NET 10 or later and Nutrient.SDK 1.0.1 or later.
  • A license covering document splitting, or an applicable trial.
  • The bundled merged_documents.pdf, or your own merged document.
  • Internet access for first-use model downloads, a writable resource cache, and sufficient memory. After downloading the resources, processing runs locally.

Open the document

Import the SDK namespace and open the merged PDF with a using statement(opens in a new tab) to release its resources after processing:

using Nutrient;
try
{
using Document document = Document.Open("merged_documents.pdf");

The default splitter combines page images and text to predict boundaries. Unless you explicitly select another vision engine, splitting reads page text with AdaptiveOcr.

Configure boundary detection

Set the threshold for starting a new document and request per-page confidence values:

DocumentSplitSettings split = document.Settings.DocumentSplitSettings;
split.BoundaryThreshold = 0.5f;
split.IncludePageConfidences = true;

A page starts a new segment when its boundary confidence meets the threshold. The first page always starts a segment. Raise BoundaryThreshold to require stronger evidence for a split; lower it to split more readily. The default is 0.5.

IncludePageConfidences is disabled by default. Enabling it helps inspect boundary decisions without another model run.

Opt in to decision-model splitting

Version 1.0.1 adds a local decision-model backend as an alternative to the default splitter. Run the packaged sample with dotnet run -- --decision-model to use it:

bool includeDocumentTypes = args.Contains("--document-types");
if (args.Contains("--decision-model") || includeDocumentTypes)
{
split.EnableDocumentDecisionSplit = true;
}

This setting replaces the default splitting backend. It doesn’t add a second score to it. The decision model is slower than the default splitter and requires its own downloaded model resources. Prepare the cache before offline use. It also accepts at most 256 pages per document, compared with 1,024 pages for the default splitter.

Without either command-line argument, the sample keeps the default splitter.

Split on document-type changes

Run dotnet run -- --document-types to enable both the decision model and per-page document classification. StreamCandidateLabels accepts a JSON array with at least two entries, each containing a key and an optional description:

if (includeDocumentTypes)
{
split.StreamCandidateLabels = """
[
{ "key": "invoice", "description": "An itemized bill for goods or services." },
{ "key": "contract", "description": "A legal agreement stating terms and obligations." },
{ "key": "identity_form", "description": "A form collecting personal identity information." },
{ "key": "other", "description": "A document that does not fit the other categories." }
]
""";
}

These labels are illustrative. Replace them with the document types your input contains. Candidate labels require EnableDocumentDecisionSplit = true; the command-line handling above enables it automatically.

The model assigns a type to each page. A change in type adds a split even when the boundary confidence is below BoundaryThreshold. Type labels only add splits; they don’t remove boundaries already detected. Two adjacent documents with the same type can therefore remain separate segments. Leave StreamCandidateLabels unset for boundary-only splitting.

Get the page ranges

Bind a vision instance to the document, call Split(), and save the response:

Vision vision = Vision.Set(document);
string resultJson = vision.Split();
File.WriteAllText("output.json", resultJson);
Console.WriteLine("Document ranges written to output.json");
}
catch (NutrientException e)
{
Console.Error.WriteLine($"Splitting failed: {e.Message}");
Environment.Exit(1);
}
catch (IOException e)
{
Console.Error.WriteLine($"Could not write output.json: {e.Message}");
Environment.Exit(1);
}

Every mode writes output.json. Save a copy before running a different mode to compare results.

Understand the output

Split() returns a top-level split object. Its segments array contains contiguous page ranges in document order:

Segment fieldMeaning
startPageFirst page, one-based and inclusive.
endPageLast page, one-based and inclusive.
pageCountNumber of pages in the segment.
boundaryConfidenceConfidence that a document starts at startPage. The forced boundary on page 1 has confidence 1.

For example, startPage: 3 and endPage: 5 identify pages 3, 4, and 5. They are source page numbers, not zero-based indexes.

With IncludePageConfidences enabled, split.pageConfidences contains one boundary confidence per page; array index zero refers to page 1.

When document-type labels are configured, segments also contain documentType and documentTypeConfidence. With per-page confidences enabled, split.pageDocumentTypes and split.pageDocumentTypeConfidences report the corresponding page-level classifications. To reconstruct splits from these diagnostics, account for type changes as well as the boundary threshold.

Handle failures and review results

Catch NutrientException for unreadable documents, pages that can’t be rendered, unavailable model resources, licensing failures, invalid candidate labels, or a BoundaryThreshold outside the range 0–1. A document with more than 1,024 pages fails with the default splitter, and one with more than 256 pages fails with the decision-model backend. Split larger inputs into smaller page ranges before processing.

Inspect predicted boundaries before automating document routing. Raise the threshold if one document is split into too many pieces; lower it if distinct documents are merged. In document-type mode, also check the candidate labels and per-page types, because type changes can add boundaries independently of the threshold.

For classifying a whole document without splitting it, refer to the document classification guide. For evaluating questions against JSON state your application already has, refer to the decision guide.