Parse configuration

The Nutrient DWS Data Extraction API extract endpoint runs in two stages. It first parses the document into structured context, and then extracts your schema’s fields from that context.

Use the parseConfig object and the inner document-level instructions string to configure the parse stage. For multipart file uploads, both fields go inside the outer multipart instructions JSON field; for JSON URL requests, both fields are top-level JSON properties.

Parse modes

parseConfig.mode selects the pipeline that runs before extraction. To compare this behavior with parsing, refer to the parse endpoint guide.

Select auto explicitly to enable per-page routing. The API uses understand when you omit parseConfig.mode. The selected mode affects extraction quality and the parse component of the request cost. With auto, the total extract cost ranges from 7.5 to 24 credits per page. For credit details, refer to the pricing guide.

{
  "schema": { "type": "object", "properties": { "total": { "type": "number" } } },
  "parseConfig": { "mode": "auto" }
}

Language hints

Set parseConfig.options.language to guide OCR for non-English documents. When you omit this option, OCR detects the language automatically. It accepts these values:

• A lowercase language name, such as "english" or "german".
• An ISO 639-2 code, such as "eng" or "deu".
• For multilingual documents, an array such as ["eng", "spa"] or a +-joined string such as "eng+spa".
• The string "auto" for automatic OCR language detection.

The following example configures OCR for English and German:

{
  "schema": { "type": "object", "properties": { "total": { "type": "number" } } },
  "parseConfig": {
    "mode": "understand",
    "options": { "language": ["eng", "deu"] }
  }
}

For the full list of codes and aliases, refer to the supported languages guide.

Free-text instructions

The inner document-level instructions string gives the extraction model document-wide guidance that doesn’t belong on a single schema field. It accepts up to 10,000 characters. For multipart uploads, this string is nested inside the outer multipart instructions JSON field:

{
  "schema": {
    "type": "object",
    "properties": {
      "line_items": {
        "type": "array",
        "items": { "type": "object", "properties": { "description": { "type": "string" } } }
      }
    }
  },
  "instructions": "Extract all line items exactly as they appear in the invoice table. Treat shipping and handling as separate line items.",
  "parseConfig": { "mode": "understand" }
}

Use instructions for cross-field rules and disambiguation. Use a field’s description for per-field guidance. For field-level descriptions, refer to the define a schema guide.

Choose a parse mode

Start with auto so the processing mode can vary by page. Choose an explicit mode when your documents or cost requirements call for it.

• Drop to structure when documents have clean, predictable layouts and you need lower cost or shorter processing time.
• Move to agentic when understand produces visible gaps, such as degraded scans, cursive or freeform handwriting, or dense visual content that requires visual reasoning.

Test a representative sample at each mode before you commit a pipeline to a mode. Compare the extracted data and citation confidence. To configure citations, refer to the citations and confidence guide.

Next steps

Use these guides to continue configuring extraction:

• Refer to the define a schema guide for field types, supported keywords, and limits.
• Refer to the citations and confidence guide for per-field grounding and confidence signals.
• Refer to the processing modes guide for a detailed comparison of parse-stage modes.