extract_fields
Extract specific fields from PDFs, images, or Office files into a custom JSON schema, returning only the values you define with per-field citations for verification.
Instructions
Pull specific named fields out of a document into a JSON shape you define, using the Nutrient DWS Data Extraction API. Reads the input file from the local file system or sandbox (if enabled), or fetches it directly from a URL — provide exactly one of filePath or url.
Unlike parse_document, which parses a whole document into elements or Markdown, extract_fields takes a JSON schema (root type: "object", with properties) and returns only the values matching it — e.g. { invoiceNumber, total, lineItems: [...] } — each with a per-field citation (bounding box, confidence, and match quality) tying it back to where it was found.
Processing modes (cost per page, parse component only — no text mode here): structure = OCR spatial parse (1.5 credits); understand = AI-augmented, default (9 credits); agentic = VLM-augmented (18 credits). Total cost per page is this parse component plus a fixed extract component, billed in Data Extraction credits — a separate balance from the Processor API credits reported by check_credits.
output.data (the extracted values) is always returned inline. Per-field citations and page geometry are large and are only kept when outputPath is provided; otherwise a note says they were omitted.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | URL of the document to extract from — fetched directly by the API instead of uploading a local file. Exactly one of filePath or url is required. | |
| mode | No | Parse mode feeding the extraction (cost/quality trade-off). No text mode — schema-guided extraction needs the structural parse (OCR/layout) that text mode skips. structure: OCR-based spatial parse (1.5 credits/page). understand: AI-augmented, the default (9 credits/page). agentic: VLM-augmented for the most complex documents (18 credits/page). Total cost per page is this parse component plus a fixed extract component, in Data Extraction credits. | understand |
| schema | Yes | JSON Schema describing the fields to extract. Root must be type: "object" with properties. Schemas are closed — do NOT set additionalProperties yourself, the API rejects a schema that sets it. Limits: 32 KB serialized, 500 fields, 50 properties per object, 5 nesting levels, enum values capped at 50. | |
| strict | No | Fail the extraction if a required field cannot be found, instead of returning a partial result. Server default: false. | |
| filePath | No | Path to the document to extract from (PDF, image, or Office file). Exactly one of filePath or url is required. Resolves to sandbox path if enabled, otherwise resolves to the local file system. | |
| language | No | OCR language(s) — full name (e.g. "german"), ISO code (e.g. "deu"), or array for multilingual docs. Leave unset for auto-detection. | |
| maxScripts | No | Maximum number of scripts to auto-detect. Only valid when language is left unset. Server default: 2. | |
| multimodal | No | Use multimodal (vision) extraction for higher accuracy on visual fields. Increases cost and latency. Server default: false. | |
| outputPath | No | Where to write the full response (data, per-field citations, and pages). Resolves to sandbox path if enabled. output.data is always returned inline regardless of this option; set it to also keep the citations. | |
| instructions | No | Free-text guidance for the extraction, e.g. clarifying an ambiguous field. Max 10000 characters. | |
| maxLanguages | No | Maximum number of languages to auto-detect. Only valid when language is left unset. Server default: 2. | |
| includeCitations | No | Include per-field citations (bounding box, confidence, match quality) in output.metadata. Server default: true. Leave unset to keep that default — passing false here disables citations. |