Classify

documents.classify scores one original file against caller-defined classes. Classify the whole document once, or return one unit per selected page.

Classify reads the original file and does not accept a parse-result source.

Basic usage

import { NdiClient, UnknownResult } from "ndi-sdk";

const client = new NdiClient();
const document = await client.documents.createUpload("mailroom-scan.pdf");
const queued = await client.documents.classify(document, {
  classes: [
    { id: "invoice", label: "Invoice", description: "A supplier invoice requesting payment" },
    { id: "contract", label: "Contract", description: "An agreement signed by two or more parties" },
    { id: "bank_statement", label: "Bank statement", description: "Periodic account activity issued by a bank" },
  ],
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: succeeded Job; job.result is a ClassifyResult

if (job.result?.result_type === "classify" && !(job.result instanceof UnknownResult)) {
  for (const unit of job.result.units) {
    console.log(unit.unknown, unit.labels);
  }
}

Method signature

classify(
  source: UploadResponse | UploadSource | UrlSource | WorkspaceFileSource,
  opts: {
    classes: ClassifyClass[];
    granularity?: "document" | "page";
    page_ranges?: PageRange[];
    parse_mode?: "low" | "medium" | "high";
    unknown_policy?: "allow" | "force_best";
    output?: ClassifyOutputOptions;
    wait_seconds?: number;
    idempotency_key?: string;
  },
): Promise<Job>

Parameters

Parameter	Type	Required	Description
`source`	upload, URL, or workspace file	Yes	Original file to classify. A prior parse job is not accepted
`opts.classes`	`ClassifyClass[]`	Yes	Caller-defined labels to score
`opts.granularity`	`"document"` / `"page"`	No	Return one unit for the file or one unit per page
`opts.page_ranges`	`PageRange[]`	No	One-based inclusive ranges. Omit for the whole document
`opts.parse_mode`	`"low"` / `"medium"` / `"high"`	No	Parsing effort. Low uses native OCR, medium routes to the best parser, and high adds page verification and correction. Defaults to low
`opts.unknown_policy`	`"allow"` / `"force_best"`	No	`allow` may mark a unit unknown. `force_best` commits an ambiguous unit to a class, but blank, unreadable, unparsed, or never-read pages stay unknown
`opts.output`	`ClassifyOutputOptions`	No	Alternative-label count and reason inclusion
`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

Unread pages are reported with a classification_unread_pages disclosure.

Returns

A Job. After success, job.result is a ClassifyResult containing units and any non-fatal disclosures. Unread pages are disclosed as classification_unread_pages.

Define classes

Each class has a stable id, display label, and model guidance:

import { type ClassifyClass } from "ndi-sdk";

const classes: ClassifyClass[] = [
  {
    id: "invoice",
    label: "Invoice",
    description: "Supplier request for payment",
    criteria: [
      "Contains an invoice number",
      "Shows an amount due",
    ],
  },
  {
    id: "purchase_order",
    label: "Purchase order",
    description: "Buyer-issued request for goods or services",
    criteria: [
      "Contains a purchase order number",
      "Issued by the buyer rather than the supplier",
    ],
  },
  {
    id: "receipt",
    label: "Receipt",
    description: "Evidence that payment was completed",
  },
];

Class IDs must be unique. Keep IDs stable when display labels or descriptions change because result labels join back to the request by class_id.

Subclasses

Use subclasses when a broad class has meaningful variants:

import { type ClassifyClass } from "ndi-sdk";

const classes: ClassifyClass[] = [
  {
    id: "agreement",
    label: "Agreement",
    description: "A signed legal agreement",
    subclasses: [
      {
        id: "msa",
        label: "Master services agreement",
        description: "Governs an ongoing service relationship",
      },
      {
        id: "sow",
        label: "Statement of work",
        description: "Defines one project's scope and fees",
      },
    ],
  },
];

Document or page classification

The default document granularity returns one unit for the entire source:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const document = await client.documents.createUpload("invoice.pdf");
const queued = await client.documents.classify(document, {
  classes: [{ id: "invoice", label: "Invoice", description: "A supplier invoice" }],
  granularity: "document",
});
// Returns: Job with one classification unit

Use page when a file contains different content on different pages:

import { NdiClient, UnknownResult } from "ndi-sdk";

const client = new NdiClient();
const document = await client.documents.createUpload("mailroom-scan.pdf");
const job = await client.jobs.wait(
  (
    await client.documents.classify(document, {
      classes: [
        { id: "invoice", label: "Invoice", description: "A supplier invoice" },
        { id: "receipt", label: "Receipt", description: "Proof of payment" },
        { id: "contract", label: "Contract", description: "A signed agreement" },
      ],
      granularity: "page",
      wait_seconds: 30,
    })
  ).job_id,
);
// Returns: ClassifyResult with one unit per selected page

if (job.result?.result_type === "classify" && !(job.result instanceof UnknownResult)) {
  for (const unit of job.result.units) {
    console.log(unit.page_range, unit.labels[0]?.class_id);
  }
}

Select pages

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const document = await client.documents.createUpload("mailroom-scan.pdf");
const queued = await client.documents.classify(document, {
  classes: [{ id: "invoice", label: "Invoice", description: "A supplier invoice" }],
  granularity: "page",
  page_ranges: [{ start: 3, end: 12 }],
  parse_mode: "medium",
});
// Returns: Job for pages 3 through 12

Handle unknown content

Value	Behavior
`allow`	A unit can return `unknown: true` when none of the requested classes fits
`force_best`	Every unit is assigned the highest-ranked requested class

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const document = await client.documents.createUpload("mailroom-scan.pdf");
const queued = await client.documents.classify(document, {
  classes: [{ id: "invoice", label: "Invoice", description: "A supplier invoice" }],
  unknown_policy: "allow",
});
// Returns: Job; unrelated content can remain unknown

Start with allow when the set of possible documents is open-ended. Use force_best only when every input must belong to your closed class set.

Configure alternatives and reasons

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const document = await client.documents.createUpload("mailroom-scan.pdf");
const queued = await client.documents.classify(document, {
  classes: [{ id: "invoice", label: "Invoice", description: "A supplier invoice" }],
  output: {
    max_alternatives: 5,
    include_reason: true,
  },
});
// Returns: Job with up to five ranked labels per unit

max_alternatives defaults to 3, accepts 1–10, and includes the winner. Reasons are included by default.

Response structure

import { NdiClient, UnknownResult } from "ndi-sdk";

const client = new NdiClient();
const job = await client.jobs.wait("classify-job-id");
// Returns: succeeded classify job

if (job.result?.result_type === "classify" && !(job.result instanceof UnknownResult)) {
  const result = job.result;

  for (const unit of result.units) {
    console.log(unit.granularity);
    console.log(unit.page_range);
    console.log(unit.unknown);

    for (const label of unit.labels) {
      console.log(label.class_id);
      console.log(label.subclass_id);
      console.log(label.label);
      console.log(label.rank);
      console.log(label.reason);
      console.log(label.confidence);
    }
  }

  console.log(result.disclosures);
}

Labels are sorted best-first. rank === 1 is the assigned class, or the top candidate when unknown === true. The reserved other ID can appear when no requested class matches. confidence is DREX’s probability for the label, averaged over the menu orders, when DREX decided it. When any other label in the unit lacks one, every such label is the share of pages or sheets assigned that class. Runner-up labels on an abstained unit keep DREX’s probability for that option. disclosures carries non-fatal notices. A classification_gap_fill disclosure names the pages that were assigned a fallback label and the label used.

Complete example

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

const classes: ClassifyClass[] = [
  { id: "invoice", label: "Invoice", description: "Supplier request for payment" },
  { id: "purchase_order", label: "Purchase order", description: "Buyer-issued order for goods or services" },
  { id: "receipt", label: "Receipt", description: "Evidence of completed payment" },
  { id: "contract", label: "Contract", description: "Agreement signed by two or more parties" },
];

const client = new NdiClient();
const document = await client.documents.createUpload("mailroom-scan.pdf");
const queued = await client.documents.classify(document, {
  classes,
  granularity: "page",
  unknown_policy: "allow",
  output: { max_alternatives: 3, include_reason: true },
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: ClassifyResult with ranked labels for every page

if (job.result?.result_type === "classify" && !(job.result instanceof UnknownResult)) {
  for (const unit of job.result.units) {
    if (unit.unknown) {
      console.log(unit.page_range, "Unknown");
    } else {
      const winner = unit.labels[0];
      console.log(unit.page_range, winner?.class_id, winner?.reason);
    }
  }
}

Error handling

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

const client = new NdiClient();
try {
  const queued = await client.documents.classify(
    await client.documents.createUpload("document.pdf"),
    { 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);
  }
}

Common failures include empty or duplicate class IDs, reserved IDs, invalid page ranges, unsupported file types, and a parse-result source.

Best practices

Separate nearby classes

Explain how similar classes differ rather than repeating their labels.

Keep IDs stable

Treat class_id as the durable join key and labels as display text.

Allow unknowns first

Avoid forcing unrelated documents into a class while developing the taxonomy.

Use page mode deliberately

Page granularity is for mixed packets; document granularity is simpler for one logical file.

Get started

Core methods

Async and utilities

Basic usage

Method signature

Parameters

Returns

Define classes

Subclasses

Document or page classification

Select pages

Handle unknown content

Configure alternatives and reasons

Response structure

Complete example

Error handling

Best practices

Separate nearby classes

Keep IDs stable

Allow unknowns first

Use page mode deliberately

Next steps

​Basic usage

​Method signature

​Parameters

​Returns

​Define classes

​Subclasses

​Document or page classification

​Select pages

​Handle unknown content

​Configure alternatives and reasons

​Response structure

​Complete example

​Error handling

​Best practices

Separate nearby classes

Keep IDs stable

Allow unknowns first

Use page mode deliberately

​Next steps

Basic usage

Method signature

Parameters

Returns

Define classes

Subclasses

Document or page classification

Select pages

Handle unknown content

Configure alternatives and reasons

Response structure

Complete example

Error handling

Best practices

Next steps