Extract

documents.extract pulls structured data from a document into a JSON object you define. Supply an inline JSON Schema or the ID of a registered schema. Every declared field receives a status. not_found means NDI examined the document and did not find the value; it is not an HTTP or job failure.

Basic usage

import { NdiClient } from "ndi-sdk";

const schema = {
  type: "object",
  properties: {
    invoice_number: {
      type: "string",
      description: "Invoice identifier shown near the top",
    },
    total: {
      type: "number",
      description: "Final amount due",
    },
  },
  required: ["invoice_number", "total"],
};

const client = new NdiClient();
const upload = await client.documents.createUpload("invoice.pdf");
const queued = await client.documents.extract(upload, {
  json_schema: schema,
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: succeeded Job; job.result is an ExtractResult

if (job.result?.result_type === "extract" && "fields" in job.result) {
  console.log(job.result.data);
  for (const field of job.result.fields) {
    console.log(field.path, field.status, field.value);
  }
}

Method signature

extract(
  source: DocumentSource | UploadResponse,
  opts: {
    json_schema?: JsonSchema;
    schema_id?: string;
    instructions?: string;
    page_ranges?: PageRange[];
    parse_mode?: "low" | "medium" | "high";
    citations?: ExtractCitationOptions;
    delivery?: "complete" | "progressive";
    wait_seconds?: number;
    idempotency_key?: string;
  },
): Promise<Job>

Parameters

Parameter	Type	Required	Description
`source`	`DocumentSource` or `UploadResponse`	Yes	Staged upload, URL, workspace file, or successful parse job
`opts.json_schema`	JSON Schema object	Yes, unless you pass `schema_id`	Inline schema describing the result. Do not send both
`opts.schema_id`	`string`	Yes, unless you pass `json_schema`	Registered schema ID (`sch_...`). Do not send both
`opts.instructions`	`string`	No	Additional guidance for filling declared fields
`opts.page_ranges`	`PageRange[]`	No	One-based inclusive ranges. Not available on a `parse_result` source
`opts.parse_mode`	`"low"` / `"medium"` / `"high"`	No	Processing effort before extraction
`opts.citations`	`ExtractCitationOptions`	No	Include source locations and quoted source text. Default on
`opts.delivery`	`"complete"` / `"progressive"`	No	Publish values before highlights when progressive. Default complete
`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

Exactly one of json_schema or schema_id is required. The SDK throws a client-side Error when both are supplied or neither is.

Returns

A Promise<Job>. On success, result.result_type === "extract". With delivery: "progressive", read the job using client.jobs.get(jobId). A running job can already contain values with enrichment_status: "pending". Continue reading the same job to receive final highlights. jobs.wait waits for terminal status. enrichment_status becomes complete or degraded; job status remains authoritative for completion or cancellation. Parquet extraction currently returns its result at completion.

Field	Description
`data`	Object shaped by the supplied schema. Missing values are `null`
`fields`	One status entry per schema leaf, including missing fields
`schema_id` / `schema_version`	Registered schema identity, or `null` for an inline schema
`converted_pdf_url`	Authenticated converted PDF for supported Office sources
`units`	Billable units
`warnings`	Non-fatal extraction notes

Define the schema

Use the supported JSON Schema subset to describe the exact shape you need:

import { NdiClient } from "ndi-sdk";

const schema = {
  type: "object",
  properties: {
    supplier: {
      type: "string",
      description: "Legal name of the supplier",
    },
    invoice_date: {
      type: "string",
      description: "Invoice issue date in YYYY-MM-DD format",
    },
    currency: {
      type: "string",
      description: "ISO currency code stated on the invoice",
    },
    total: {
      type: "number",
      description: "Final invoice total after tax",
    },
  },
  required: ["supplier", "invoice_date", "currency", "total"],
};

const client = new NdiClient();
const upload = await client.documents.createUpload("invoice.pdf");
const job = await client.documents.extract(upload, { json_schema: schema });
// Returns: Promise<Job>

Write specific descriptions

Descriptions guide extraction and should distinguish similar values:

const schema = {
  type: "object",
  properties: {
    subtotal: {
      type: "number",
      description: "Amount before tax and shipping",
    },
    tax: {
      type: "number",
      description: "Tax amount, not tax rate",
    },
    amount_due: {
      type: "number",
      description: "Final outstanding balance after payments",
    },
  },
};

instructions can clarify how to fill declared fields, but cannot add fields that the schema does not declare:

import { NdiClient } from "ndi-sdk";

const schema = {
  type: "object",
  properties: { total: { type: "number" } },
};

const client = new NdiClient();
const upload = await client.documents.createUpload("invoice.pdf");
const job = await client.documents.extract(upload, {
  json_schema: schema,
  instructions: "Use the final totals section, not line-item amounts.",
});
// Returns: Promise<Job>

Validate before extracting

Schema validation creates no job and spends no credits:

import { NdiClient } from "ndi-sdk";

const schema = {
  type: "object",
  properties: { total: { type: "number" } },
};

const client = new NdiClient();
const check = await client.documents.validateExtractSchema({
  json_schema: schema,
});
// Returns: Promise<ExtractSchemaValidationResponse>

if (!check.valid) {
  for (const error of check.errors ?? []) {
    console.log(error.path, error.message);
  }
}

The response contains every discovered error and the normalized schema when validation succeeds.

Use a registered schema

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("invoice.pdf");
const job = await client.documents.extract(upload, {
  schema_id: "sch_01JZ8WQ4VK2P7T1J0Y6S4M3N2B",
});
// Returns: Promise<Job>; result includes schema_id and schema_version

Create and publish reusable schemas through the REST extraction-schema endpoints (POST /v1/extraction-schemas). The TypeScript SDK does not expose a schema-registry namespace. See Extraction schemas.

Source options

Extract accepts staged uploads, HTTPS URLs, workspace files, and successful parse jobs. Reuse a parse when another operation already produced the content:

import { NdiClient } from "ndi-sdk";

const schema = {
  type: "object",
  properties: { total: { type: "number" } },
};

const client = new NdiClient();
const upload = await client.documents.createUpload("invoice.pdf");
const parsed = await client.jobs.wait(
  (await client.documents.parse(upload, { wait_seconds: 30 })).job_id,
);
const queued = await client.documents.extract(
  { type: "parse_result", job_id: parsed.job_id },
  { json_schema: schema },
);
// Returns: Promise<Job>; the earlier parse is reused

page_ranges is unavailable with a parse_result source because the selected content is already fixed. Use page ranges when extracting from an original source:

import { NdiClient } from "ndi-sdk";

const schema = {
  type: "object",
  properties: { total: { type: "number" } },
};

const client = new NdiClient();
const upload = await client.documents.createUpload("invoice.pdf");
const job = await client.documents.extract(upload, {
  json_schema: schema,
  page_ranges: [{ start: 1, end: 5 }],
  parse_mode: "medium",
});
// Returns: Promise<Job> for pages 1 through 5

Citations

Citations are enabled by default. Each field can carry the location and source text that supports its value:

import { NdiClient } from "ndi-sdk";

const schema = {
  type: "object",
  properties: { total: { type: "number" } },
};

const client = new NdiClient();
const upload = await client.documents.createUpload("invoice.pdf");
const job = await client.jobs.wait(
  (
    await client.documents.extract(upload, {
      json_schema: schema,
      citations: { enabled: true, include_source_text: true },
      wait_seconds: 30,
    })
  ).job_id,
);
// Returns: ExtractResult whose fields include citations

if (job.result?.result_type === "extract" && "fields" in job.result) {
  for (const field of job.result.fields) {
    for (const citation of field.citations ?? []) {
      console.log(field.path, citation.location, citation.source_text);
    }
  }
}

Disable citations only when you do not need source verification:

import { NdiClient } from "ndi-sdk";

const schema = {
  type: "object",
  properties: { total: { type: "number" } },
};

const client = new NdiClient();
const upload = await client.documents.createUpload("invoice.pdf");
const job = await client.documents.extract(upload, {
  json_schema: schema,
  citations: { enabled: false },
});
// Returns: Promise<Job>; ExtractResult.fields have no citations

Response structure

import { NdiClient } from "ndi-sdk";

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

if (job.result?.result_type === "extract" && "fields" in job.result) {
  const result = job.result;
  console.log(result.data?.["invoice_number"]);
  console.log(result.data?.["total"]);

  for (const field of result.fields) {
    console.log(field.path);        // JSON Pointer, such as /invoice_number
    console.log(field.status);      // found, not_found, or ambiguous
    console.log(field.value);
    console.log(field.confidence);
    console.log(field.citations);
  }
}

Use data for the schema-shaped answer and fields for verification and status handling. Missing values remain present as null; they are not silently dropped.

Extract response format

Review field statuses, confidence, citation locations, warnings, and registered schema metadata.

Complete example

import { NdiClient } from "ndi-sdk";

const schema = {
  type: "object",
  properties: {
    invoice_number: {
      type: "string",
      description: "Supplier invoice identifier",
    },
    supplier: {
      type: "string",
      description: "Legal supplier name",
    },
    amount_due: {
      type: "number",
      description: "Final outstanding balance",
    },
  },
  required: ["invoice_number", "supplier", "amount_due"],
};

const client = new NdiClient();
const check = await client.documents.validateExtractSchema({
  json_schema: schema,
});
if (!check.valid) {
  throw new Error(JSON.stringify(check.errors));
}

const upload = await client.documents.createUpload("invoice.pdf");
const parsed = await client.jobs.wait(
  (await client.documents.parse(upload, { wait_seconds: 30 })).job_id,
  { timeout: 600 },
);
const queued = await client.documents.extract(
  { type: "parse_result", job_id: parsed.job_id },
  {
    json_schema: schema,
    instructions: "Read the final balance after credits and prior payments.",
    wait_seconds: 30,
  },
);
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: ExtractResult with schema-shaped data and per-field evidence

if (job.result?.result_type === "extract" && "fields" in job.result) {
  console.log(job.result.data);
  const missing = job.result.fields
    .filter((f) => f.status === "not_found")
    .map((f) => f.path);
  console.log("Missing:", missing);
}

Error handling

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

const schema = {
  type: "object",
  properties: { total: { type: "number" } },
};

const client = new NdiClient();
try {
  const upload = await client.documents.createUpload("invoice.pdf");
  const queued = await client.documents.extract(upload, {
    json_schema: schema,
  });
  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;
  }
}

Client-side Error is thrown when both json_schema and schema_id are set, or when neither is set.

Best practices

Validate first

Preflight a schema without creating a job or spending credits.

Describe each field

State which value to select, how to distinguish it, and the expected representation.

Get started

Core methods

Async and utilities

Basic usage

Method signature

Parameters

Returns

Define the schema

Write specific descriptions

Validate before extracting

Use a registered schema

Source options

Citations

Response structure

Extract response format

Complete example

Error handling

Best practices

Validate first

Describe each field

Keep citations on

Inspect not_found

Next steps

​Basic usage

​Method signature

​Parameters

​Returns

​Define the schema

​Write specific descriptions

​Validate before extracting

​Use a registered schema

​Source options

​Citations

​Response structure

Extract response format

​Complete example

​Error handling

​Best practices

Validate first

Describe each field

Keep citations on

Inspect not_found

​Next steps

Basic usage

Method signature

Parameters

Returns

Define the schema

Write specific descriptions

Validate before extracting

Use a registered schema

Source options

Citations

Response structure

Complete example

Error handling

Best practices

Next steps