Split

documents.split finds logical documents inside one file. PDFs and other page-based sources become ordered page-range segments. Workbooks become one segment per worksheet, classified against the classes you provide.

Basic usage

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const packet = await client.documents.createUpload("vendor-packet.pdf");
const queued = await client.documents.split(packet, {
  classes: [
    { id: "invoice", label: "Invoice", description: "A supplier invoice" },
    { id: "receipt", label: "Receipt", description: "Proof of payment" },
  ],
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: succeeded Job; job.result is a SplitResult

if (job.result?.result_type === "split" && "segments" in job.result) {
  for (const segment of job.result.segments) {
    console.log(segment.split_class, segment.start_page, segment.end_page);
  }
}

Method signature

split(
  source: DocumentSource | UploadResponse,
  opts: {
    classes: SplitCategory[];
    unknown_policy?: "include" | "force" | "error";
    page_ranges?: PageRange[];
    parse_mode?: "low" | "medium" | "high";
    overlap_policy?: "exclusive" | "shared_boundary_page";
    quality?: "auto";
    split_rules?: string;
    output?: SplitOutputOptions;
    wait_seconds?: number;
    idempotency_key?: string;
  },
): Promise<Job>

Parameters

Parameter	Type	Required	Description
`source`	`DocumentSource` or `UploadResponse`	Yes	Packet, workbook, URL, workspace file, or successful parse job
`opts.classes`	`SplitCategory[]`	Yes	Document or worksheet classes to identify
`opts.unknown_policy`	`"include"` / `"force"` / `"error"`	No	Keep unmatched content, force its best class, or fail
`opts.page_ranges`	`PageRange[]`	No	One-based inclusive page ranges. Not supported for spreadsheets
`opts.parse_mode`	`"low"` / `"medium"` / `"high"`	No	Processing effort before splitting
`opts.overlap_policy`	`"exclusive"` / `"shared_boundary_page"`	No	Keep segments disjoint, or include a boundary page in both adjacent segments
`opts.quality`	`"auto"`	No	Only accepted value
`opts.split_rules`	`string`	No	Additional natural-language rules for finding boundaries
`opts.output`	`SplitOutputOptions`	No	Include segment markdown or materialize segment files
`opts.wait_seconds`	`number`	No	Hold the submission request open for up to 300 seconds
`opts.idempotency_key`	`string`	No	Override the key the SDK normally mints

Returns

A Promise<Job>. After success, result.result_type === "split" and result.segments is the ordered cut list.

Field	Description
`file_name`	Name of the source
`lane`	Processing lane
`page_count`	Number of source pages or logical spreadsheet pages
`segments`	Ordered classified and unclassified cuts
`units`	Billable units

Define classes

Each class needs a stable id, display label, and a description that distinguishes it from nearby classes:

import { NdiClient, type SplitCategory } from "ndi-sdk";

const classes: SplitCategory[] = [
  {
    id: "purchase_order",
    label: "Purchase order",
    description: "Buyer-issued order listing requested goods or services",
  },
  {
    id: "invoice",
    label: "Invoice",
    description: "Supplier request for payment with an invoice number",
  },
  {
    id: "receipt",
    label: "Receipt",
    description: "Evidence that a payment was completed",
  },
  {
    id: "bank_statement",
    label: "Bank statement",
    description: "Periodic account activity issued by a bank",
  },
];

Avoid labels whose descriptions overlap completely. The id is what appears in result joins; keep it stable if you revise display text.

Subclasses and instance keys

Add subclasses for finer segment labels and an instance key when each segment should carry a document identifier:

import { NdiClient, type SplitCategory } from "ndi-sdk";

const invoice: SplitCategory = {
  id: "invoice",
  label: "Invoice",
  description: "A supplier request for payment",
  subclasses: [
    {
      id: "utility",
      label: "Utility invoice",
      description: "Invoice for electricity, gas, water, or telecom",
    },
    {
      id: "goods",
      label: "Goods invoice",
      description: "Invoice for purchased physical goods",
    },
  ],
  instance_key: {
    name: "invoice_number",
    description: "Supplier invoice identifier",
  },
};

The selected subclass is returned with the segment classification. segment.instance carries the requested key and extracted value when one is available.

Control unmatched content

unknown_policy determines what happens when content matches none of the classes:

Value	Behavior
`"include"`	Keep an unclassified segment. This is the default
`"force"`	Assign the closest requested class
`"error"`	Fail instead of returning unmatched content

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const packet = await client.documents.createUpload("packet.pdf");
const queued = await client.documents.split(packet, {
  classes: [
    { id: "invoice", label: "Invoice", description: "A supplier invoice" },
  ],
  unknown_policy: "include",
});
// Returns: Promise<Job>; unmatched pages remain as unclassified segments

Use "include" when completeness matters. Use "force" only when every page must belong to one of a closed set of classes.

Page selection and parse mode

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const packet = await client.documents.createUpload("packet.pdf");
const queued = await client.documents.split(packet, {
  classes: [
    {
      id: "statement",
      label: "Statement",
      description: "Periodic financial statement",
    },
  ],
  page_ranges: [{ start: 3, end: 40 }],
  parse_mode: "medium",
});
// Returns: Promise<Job> covering pages 3 through 40

Page ranges are not supported for spreadsheet sources. Use "medium" or "high" only when the default parse is not sufficient; higher modes add latency.

Split rules

Use split_rules for a boundary convention the class descriptions do not express:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const packet = await client.documents.createUpload("packet.pdf");
const queued = await client.documents.split(packet, {
  classes: [
    { id: "invoice", label: "Invoice", description: "A supplier invoice" },
  ],
  split_rules:
    "Start a new invoice when the invoice number changes. " +
    "Attach continuation pages to the preceding invoice.",
});
// Returns: Promise<Job> using the additional boundary guidance

Use overlap_policy: "shared_boundary_page" when the page at a detected boundary belongs to both neighboring documents. The default "exclusive" policy keeps every source page in only one segment.

Include content or files

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const packet = await client.documents.createUpload("packet.pdf");
const job = await client.jobs.wait(
  (
    await client.documents.split(packet, {
      classes: [
        {
          id: "invoice",
          label: "Invoice",
          description: "A supplier invoice",
        },
      ],
      output: { include_content: true, materialize_files: true },
      wait_seconds: 30,
    })
  ).job_id,
);
// Returns: SplitResult with segment markdown and downloadable artifacts

if (job.result?.result_type === "split" && "segments" in job.result) {
  for (const segment of job.result.segments) {
    console.log(segment.content);
    for (const artifact of segment.artifacts ?? []) {
      console.log(artifact.url);
    }
  }
}

Document segments are materialized only when requested. Spreadsheet segments always include a single-sheet .xlsx artifact.

Response structure

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
// After client.jobs.wait returns a succeeded split job:
const job = await client.jobs.wait("job_01JZ8WQ4VK2P7T1J0Y6S4M3N2B");

if (job.result?.result_type === "split" && "segments" in job.result) {
  for (const segment of job.result.segments) {
    console.log(segment.sequence);
    console.log(segment.status);                    // matched or unclassified
    console.log(segment.split_class);               // winning class, or null
    console.log(segment.split_classes);             // class hierarchy, when returned
    console.log(segment.start_page, segment.end_page);
    console.log(segment.sheet_name);                // spreadsheet sources
    console.log(segment.instance);                  // requested per-segment identifier
    console.log(segment.classification_confidence);
    console.log(segment.boundary_confidence);
    console.log(segment.content);
    console.log(segment.artifacts);
    console.log(segment.warnings);
  }
}

Page-based segments use start_page and end_page. Spreadsheet segments use sheet_name; their page values correspond to the worksheet’s one-based position. JSON sources may use json_pointer. classification_confidence and boundary_confidence contain a readable band and an optional score. "unavailable" means no score was produced, not zero confidence.

Reuse a parse

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("packet.pdf");
const parsed = await client.jobs.wait(
  (await client.documents.parse(upload, { wait_seconds: 30 })).job_id,
);
const queued = await client.documents.split(
  { type: "parse_result", job_id: parsed.job_id },
  {
    classes: [
      { id: "invoice", label: "Invoice", description: "A supplier invoice" },
    ],
  },
);
// Returns: Promise<Job>; NDI reuses the successful ParseResult

Complete example

import { NdiClient, type SplitCategory } from "ndi-sdk";

const classes: SplitCategory[] = [
  { id: "purchase_order", label: "Purchase order", description: "Buyer-issued order" },
  { id: "invoice", label: "Invoice", description: "Supplier request for payment" },
  { id: "receipt", label: "Receipt", description: "Evidence of completed payment" },
  { id: "bank_statement", label: "Bank statement", description: "Periodic account activity from a bank" },
];

const client = new NdiClient();
const packet = await client.documents.createUpload("vendor-packet.pdf");
const queued = await client.documents.split(packet, {
  classes,
  unknown_policy: "include",
  split_rules: "Start a new segment when the document identifier changes.",
  output: { include_content: true },
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: SplitResult with ordered cuts and inline content

if (job.result?.result_type === "split" && "segments" in job.result) {
  console.log(`Found ${job.result.segments.length} segments`);
  for (const segment of job.result.segments) {
    const label =
      segment.split_class != null ? segment.split_class.label : "Unclassified";
    console.log(label, segment.start_page, segment.end_page);
  }
}

Error handling

import { NdiClient, InvalidRequestError, JobFailedError } from "ndi-sdk";

const client = new NdiClient();
try {
  const packet = await client.documents.createUpload("packet.pdf");
  const queued = await client.documents.split(packet, {
    classes: [
      { id: "invoice", label: "Invoice", description: "A supplier invoice" },
    ],
  });
  const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
  // Returns: succeeded Job, or throws for request/job failure
} catch (err) {
  if (err instanceof InvalidRequestError) {
    console.log(err.code, err.message);
  } else if (err instanceof JobFailedError) {
    console.log(err.job.status, err.job.error);
  } else {
    throw err;
  }
}

Common failures include empty or invalid classes, unsupported file types, spreadsheet page ranges, and unknown_policy: "error" when content is unclassified.

Best practices

Define distinct classes

Give each class a stable ID and a description that separates it from adjacent classes.

Keep unknowns visible

Start with unknown_policy: "include" so unexpected packet content is not silently forced.

Add rules for boundaries

Use split_rules for continuation pages or identifier changes, not to replace class descriptions.

Materialize only when needed

Request files when downstream systems need individual documents; use inline content for inspection.

Get started

Core methods

Async and utilities

Basic usage

Method signature

Parameters

Returns

Define classes

Subclasses and instance keys

Control unmatched content

Page selection and parse mode

Split rules

Include content or files

Response structure

Reuse a parse

Complete example

Error handling

Best practices

Define distinct classes

Keep unknowns visible

Add rules for boundaries

Materialize only when needed

Next steps

​Basic usage

​Method signature

​Parameters

​Returns

​Define classes

​Subclasses and instance keys

​Control unmatched content

​Page selection and parse mode

​Split rules

​Include content or files

​Response structure

​Reuse a parse

​Complete example

​Error handling

​Best practices

Define distinct classes

Keep unknowns visible

Add rules for boundaries

Materialize only when needed

​Next steps

Basic usage

Method signature

Parameters

Returns

Define classes

Subclasses and instance keys

Control unmatched content

Page selection and parse mode

Split rules

Include content or files

Response structure

Reuse a parse

Complete example

Error handling

Best practices

Next steps