Document Extraction

Document Extraction (ADE)

Overview

LandingAI's Agentic Document Extraction (ADE) is a document processing service that parses, extracts, and classifies documents without templates or training. The REST APIs are the primary interface. Official libraries wrap them for Python (landingai-ade on PyPI) and TypeScript (landingai-ade on npm).

ADE has two API generations. The v2 APIs (powered by DPT-3) are the current generation for parsing and extraction. Several capabilities exist only as v1 APIs and remain fully supported.

Every linked docs page can be fetched as raw Markdown by appending .md to its URL (for example, https://docs.landing.ai/dpt3/parse.md). A page index lives at https://docs.landing.ai/llms.txt. Full request and response contracts are in the API reference (linked per endpoint below).

Which API Version? {#which-api-version}

Use the v2 APIs by default. Route to v1 only when one of these applies:

• The user has existing code calling the /v1/ade/* endpoints (or v1 library methods client.parse() / client.extract()) and has not asked to migrate.
• The document is a spreadsheet (XLSX, CSV) or a legacy binary Office file (DOC, PPT); only v1 Parse accepts those. v2 Parse accepts PDFs, images, and modern Office documents (DOCX, PPTX, ODT, RTF).
• The file is password-protected (v2 rejects it with HTTP 422; v1 accepts a password parameter).
• The pipeline needs custom figure prompts or v1-style page splits (split=page).
• The pipeline feeds Parse output into the v1 Section or v1 Split APIs, which require the v1 Parse response shape.

To move an existing v1 pipeline to v2, follow https://docs.landing.ai/dpt3/migration-guide.

Do not mix versions within one pipeline, except as this matrix allows:

The v1 Classify API takes the raw document, not Parse output, so it composes with either version.

API Drift: Your Prior Knowledge May Be Stale

If you have seen ADE code before, it was probably v1. These v1 idioms cause silent wrong-output bugs in v2 code:

For the full v1-to-v2 request and response mapping, see https://docs.landing.ai/dpt3/migration-guide.

Setup

API Key

All endpoints authenticate with the same header: Authorization: Bearer YOUR_API_KEY. Get a key at https://va.landing.ai/settings/api-key and set it as the VISION_AGENT_API_KEY environment variable (both libraries read it automatically). Before asking the user for a key, check for an existing .env file in the working directory and in this skill's own directory (skills/document-extraction/.env); a .env-sample template sits next to this file. Keys are region-specific; for EU endpoints and data residency see https://docs.landing.ai/dpt3/eu.

Libraries (optional)

• Python: pip install landingai-ade (v1.17.0 or later covers everything in this skill). Guide: https://docs.landing.ai/dpt3/ade-python
• TypeScript: npm install landingai-ade (v2.12.0 or later covers everything in this skill). Guide: https://docs.landing.ai/dpt3/ade-typescript

When writing scripts, use the user's language and environment. Never install packages globally; use the project's virtualenv or package.json.

Core Flow: Parse, Extract, Then Ground (v2)

Parse converts a document into Markdown plus structure. Extract pulls schema-defined fields from that Markdown. Run both as jobs on the standard service tier: create the job, then call wait() (or poll GET .../jobs/{job_id}) for the finished job. Standard jobs cost half the credits of priority; see Processing Modes below for when to leave this default. Keep the trailing <!-- doc_id=... --> comment when saving Markdown; v2 Extract reads it to link the extraction back to its parse job.

Step 1: Parse. Jobs accept PDFs, images, and Office documents (DOCX, PPTX, ODT, RTF), up to 1 GiB for PDFs and 50 MiB for images; for the current page limits, see https://docs.landing.ai/dpt3/rate-limits. Office files are converted to PDF before parsing; the conversion can change layout and page count, and page-based limits and credits apply to the converted PDF's page count (https://docs.landing.ai/dpt3/file-types). Models: dpt-3-pro-latest (default, highest quality) or dpt-3-verity (preview: lower latency and credits, for digitally created text documents only; renamed from dpt-3-fast, whose values still work). DPT-3 Verity does not read scans, handwriting, or non-Latin scripts, outputs plain Markdown without heading or bold formatting, and adds per-word confidence scores. Comparison and snapshot values: https://docs.landing.ai/dpt3/parse-models.

bashCopy code
mkdir -p output
curl -X POST 'https://api.ade.landing.ai/v2/parse/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@document.pdf' \
  -F 'model=dpt-3-pro-latest' \
  -F 'service_tier=standard'

# The create response is {"job_id": "...", "status": "pending", ...}.
# Repeat this request with that job_id until status is completed or failed.
# A completed job carries the parse response under result; save result.markdown
# from this file as output/parse-output.md for Step 2 (the library examples do this).
curl 'https://api.ade.landing.ai/v2/parse/jobs/JOB_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY' -o output/parse-response.json

pythonCopy code
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()
Path("output").mkdir(exist_ok=True)

job = client.v2.parse_jobs.create(
    document=Path("document.pdf"),
    model="dpt-3-pro-latest",
    service_tier="standard",
)
# wait() polls until the job finishes. raise_on_failure turns a failed job into
# JobFailedError instead of returning a job whose result is None.
done = client.v2.parse_jobs.wait(job.job_id, timeout=3600, raise_on_failure=True)
Path("output/parse-response.json").write_text(done.result.model_dump_json(indent=2), encoding="utf-8")
Path("output/parse-output.md").write_text(done.result.markdown, encoding="utf-8")

typescriptCopy code
import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();
fs.mkdirSync("output", { recursive: true });

const job = await client.v2.parseJobs.create({
  document: fs.createReadStream("document.pdf"),
  model: "dpt-3-pro-latest",
  service_tier: "standard",
});
// wait() polls until the job finishes. raiseOnFailure turns a failed job into
// JobFailedError instead of returning a job whose result is null.
const done = await client.v2.parseJobs.wait(job.job_id, { timeout: 3_600_000, raiseOnFailure: true });
const parsed = done.result as LandingAIADE.V2ParseResponse;
if (!parsed.markdown) {
  throw new Error(`Job ${job.job_id} returned no Markdown (status: ${done.status}).`);
}
fs.writeFileSync("output/parse-response.json", JSON.stringify(parsed, null, 2));
fs.writeFileSync("output/parse-output.md", parsed.markdown);

Three things to get right with jobs:

• The output is nested under result. A finished job is {job_id, status, result, ...}. When status is completed, the parse response (markdown, structure, metadata) is result, so read done.result.markdown, not done.markdown. When status is failed, result is null and error carries a code and message; the library wait() calls above turn that into JobFailedError.
• wait() has a 10-minute default timeout (timeout=600 seconds in Python, timeout: 600000 milliseconds in TypeScript). When it expires, wait() raises JobWaitTimeoutError but the job keeps running server-side. Pass a longer timeout for large documents on standard, as above, or catch the error and resume with parse_jobs.get(job_id) / parseJobs.get(jobId).
• Save the full response, not only the Markdown. Job create methods do not accept save_to / saveTo; write result to disk yourself as shown, or pass output_save_url (see Processing Modes below). The saved JSON carries structure and grounding, which every cropping, table, and RAG workflow below needs.

Useful options (multipart field with a JSON value): {"pages": [1, 3]} (1-indexed page selection; any page beyond the document's last page rejects the whole request with HTTP 422, or fails the job after it starts), {"blocks": {"table": {"format": "markdown"}}} (pipe-syntax tables instead of HTML). Full contract: Parse API reference, https://docs.landing.ai/dpt3/parse-input.

Step 2: Extract. The schema is a JSON Schema object; descriptions guide the extraction, so treat them as prompts. The optional model field pins an extraction model snapshot (extract-latest is the default; pin a dated snapshot in production, because a new default snapshot can change extraction results).

bashCopy code
curl -X POST 'https://api.ade.landing.ai/v2/extract/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'markdown=@output/parse-output.md' \
  -F 'schema={"type":"object","properties":{"invoice_number":{"type":"string","description":"Invoice number"},"total_amount":{"type":"number","description":"Total amount in USD"}}}' \
  -F 'service_tier=standard'

# Repeat with the returned job_id until status is completed or failed.
curl 'https://api.ade.landing.ai/v2/extract/jobs/JOB_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY' -o output/extract-response.json

pythonCopy code
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()

job = client.v2.extract_jobs.create(
    markdown=Path("output/parse-output.md").read_text(encoding="utf-8"),
    schema={
        "type": "object",
        "properties": {
            "invoice_number": {"type": "string", "description": "Invoice number"},
            "total_amount": {"type": "number", "description": "Total amount in USD"},
        },
    },
    service_tier="standard",
)
done = client.v2.extract_jobs.wait(job.job_id, timeout=3600, raise_on_failure=True)
Path("output/extract-response.json").write_text(done.result.model_dump_json(indent=2), encoding="utf-8")
print(done.result.extraction)

typescriptCopy code
import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();

const job = await client.v2.extractJobs.create({
  markdown: fs.readFileSync("output/parse-output.md", "utf8"),
  schema: {
    type: "object",
    properties: {
      invoice_number: { type: "string", description: "Invoice number" },
      total_amount: { type: "number", description: "Total amount in USD" },
    },
  },
  service_tier: "standard",
});
const done = await client.v2.extractJobs.wait(job.job_id, { timeout: 3_600_000, raiseOnFailure: true });
const extracted = done.result as LandingAIADE.V2ExtractResult;
fs.writeFileSync("output/extract-response.json", JSON.stringify(extracted, null, 2));
console.log(extracted.extraction);

The libraries also accept a Pydantic class (Python) or Zod schema (TypeScript) directly on schema. Full contract: Extract API reference, https://docs.landing.ai/dpt3/extract-input.

Step 3: Ground (optional). Ground maps each extracted field back to the parse blocks it was quoted from, returning page numbers and bounding boxes, so you don't have to join ranges by hand. Pass Step 1's structure and Step 2's extraction_metadata; it runs synchronously, needs no job, and is always free. Each multipart field carries one JSON-serialized object, so write the two out to their own files first: on a curl-saved job response both sit under .result, while the library examples above already wrote them unwrapped.

bashCopy code
curl -X POST 'https://api.ade.landing.ai/v2/ground' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'extraction_metadata=<output/extraction-metadata.json' \
  -F 'structure=<output/structure.json' \
  -o output/ground-response.json

pythonCopy code
import json
from pathlib import Path
from landingai_ade import LandingAIADE

client = LandingAIADE()
parse_result = json.loads(Path("output/parse-response.json").read_text())
extract_result = json.loads(Path("output/extract-response.json").read_text())

# A mismatched pair is not an error: Ground would return 200 with wrong boxes.
assert extract_result["metadata"]["doc_id"] == parse_result["metadata"]["job_id"]

ground_response = client.v2.ground(
    extraction_metadata=extract_result["extraction_metadata"],
    structure=parse_result["structure"],
)
print(ground_response.grounding)

typescriptCopy code
import fs from "fs";
import LandingAIADE from "landingai-ade";

const client = new LandingAIADE();
const parseResult = JSON.parse(fs.readFileSync("output/parse-response.json", "utf8"));
const extractResult = JSON.parse(fs.readFileSync("output/extract-response.json", "utf8"));

// A mismatched pair is not an error: Ground would return 200 with wrong boxes.
if (extractResult.metadata.doc_id !== parseResult.metadata.job_id) {
  throw new Error("The extraction and the structure came from different parses.");
}

const groundResponse = await client.v2.ground({
  extraction_metadata: extractResult.extraction_metadata,
  structure: parseResult.structure,
});
console.log(groundResponse.grounding);

Pair each extraction with its own parse. Ranges shift between parses, even of the same file, so an extraction grounds only against the structure it was extracted from. A mismatched pair is not an error: Ground returns HTTP 200 with plausible boxes that land on the wrong content, and nothing in the response marks it. Check the pairing in code before rendering anything, by comparing the Extract response's metadata.doc_id with the Parse response's metadata.job_id. Re-parsing a document means re-running its extraction too.

Organizations with Zero Data Retention enabled get HTTP 501 from Ground instead of a result; see "Reading v2 Responses" below for the manual fallback. Full contract: Ground API reference, https://docs.landing.ai/dpt3/ground.

Reading v2 Responses

Parse returns three top-level fields (https://docs.landing.ai/dpt3/parse-response); on a finished job they sit under result:

• markdown: the whole document in reading order. Every range in the response indexes into this string using Unicode code point offsets.
• structure: a document node whose children are pages; each page's children are blocks (text, table, table_cell, figure, marginalia, attestation, logo, card, scan_code). Tables nest their cells. Block ids (text-0, table_cell-3) are unique per response but not stable across re-parses.
• metadata: job_id, model_version, page_count, failed_pages (1-indexed), duration_ms, billing.

Every node carries an inline grounding object: page (1-indexed), range ({start, end}, end exclusive), and box (xmin/ymin/xmax/ymax, each normalized 0 to 1). To get a block's text, slice markdown[range.start:range.end]. To get pixels, multiply box values by the rendered page dimensions. Leaf blocks also carry atomic_grounding for fine-grained highlighting; its granularity depends on the model. DPT-3 Pro emits one entry per visual line (table cells have none). DPT-3 Verity emits one entry per word, table cells included, and each word entry carries a confidence score (0 to 1) for how certain the model is it transcribed the word correctly. Confidence appears only on word entries; block, table, and page groundings never carry one, so to score a block, take the minimum across its word entries. Use low scores to route transcriptions to review, or re-parse the document with DPT-3 Pro. DPT-3 Pro returns no confidence scores.

Markdown format details (page breaks, <figure> elements, attestation labels, the trailing doc_id comment): https://docs.landing.ai/dpt3/parse-response.

Extract returns (https://docs.landing.ai/dpt3/extract-response):

• extraction: values matching the schema. Fields the model cannot find come back as null (arrays as []).
• extraction_metadata: mirrors extraction with each leaf replaced by {"value": ..., "ranges": [...]}. Each range indexes into the input Markdown; a synthesized value has null ranges. For a field's bounding box, call Ground (Core Flow Step 3 above) with this extraction_metadata and the parse's structure; it does the range-to-block join server-side. Compute it by hand only as the documented fallback for Zero Data Retention organizations, where Ground returns HTTP 501: find the parse blocks whose grounding.range overlaps the field's range, then use those blocks' grounding.box.
• metadata.doc_id: the originating parse job, when the input Markdown carried the doc_id comment.

Ground returns grounding, a tree mirroring the extraction_metadata you sent: objects and arrays keep their shape, and each {value, ranges} leaf becomes the list of blocks its ranges overlap. Each entry carries block_id, type, parent_id (on nested blocks, naming the enclosing one), the block's own {page, range, box}, and the overlapping subset of its atomic_grounding. Two leaves carry no blocks, for different reasons: null means the field had no ranges, so nothing was quoted for it (the model synthesized the value or found none), while [] means valid ranges matched no block, which usually means the two inputs came from different parses. Handle them separately. A value inside a table matches both the table and its table_cell, so pick whichever your highlight needs (https://docs.landing.ai/dpt3/ground).

Partial results (HTTP 206): Parse sets metadata.failed_pages and per-page status; Extract sets schema_violation_error and warnings. Data is still returned and credits are consumed. Errors: every v2 error body has a stable code and a human-readable message; branch on code, never on message text. Credits are consumed only on 200/206; error responses are free, and async jobs bill only when they complete. Per-endpoint error tables: parse-troubleshoot, extract-troubleshoot.

Processing Modes and Service Tiers (v2)

Every v2 request runs on a service tier, standard or priority. Jobs default to standard and accept service_tier to switch. The sync endpoints (POST /v2/parse, POST /v2/extract; client.v2.parse / client.v2.extract in the libraries) always run at priority, return the result inline, accept save_to / saveTo, and reject service_tier and output_save_url. Ground (POST /v2/ground) is synchronous only, with no Jobs variant or service_tier choice; its response always reports billing.service_tier: "priority", but the call itself is always free.

When you write a script or pipeline for a user, stay on standard jobs unless the user asks for faster turnaround; a script the user runs later is not interactive work. When they do ask, switch to priority jobs, which keep the batch and large-file handling. Use sync only for a single small document whose result the user needs in the same call, and pass save_to / saveTo so the full response lands on disk.

Sync requests and priority jobs share one per-minute page limit. A single document with more pages than that limit returns HTTP 429 on every attempt; retrying never helps, so submit it as a standard job, which takes up to 6,000 pages. Turnaround times are estimates, and rate limits depend on the pricing plan, so check https://docs.landing.ai/dpt3/sync-async and https://docs.landing.ai/dpt3/rate-limits for current values rather than assuming them.

Instead of polling, you can register a webhook endpoint (in the Playground settings; there is no management API) to receive signed parse.succeeded, parse.failed, extract.succeeded, and extract.failed events when jobs finish: https://docs.landing.ai/dpt3/webhooks.

Both job create endpoints accept output_save_url (a presigned URL where the result is delivered instead of the poll response; recommended with zero data retention). The URL must stay valid until the job completes, not just at submission: an expired or soon-expiring URL is rejected at creation with HTTP 422 and no credits consumed, so sign it with a validity that outlives the job. Under Zero Data Retention (https://docs.landing.ai/ade/zdr), a v2 job result is deleted as soon as you fetch it, and a never-fetched result is deleted 24 to 48 hours after the job completes; persist the first completed poll response immediately (as Core Flow does), because polling again returns HTTP 410 (result_expired). With output_save_url, the result is delivered to your storage, then deleted immediately. Guides: parse-async, extract-async. API reference: parse jobs, extract jobs.

v1 APIs Without a v2 Equivalent

Classify: Page-Level Classification

Assigns a class to each page of a raw document (not Parse output), so it composes with v2 pipelines: classify first, then route pages to parsing. Guide: https://docs.landing.ai/ade/ade-classify. API reference: ade-classify.

bashCopy code
curl -X POST 'https://api.va.landing.ai/v1/ade/classify' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@batch.pdf' \
  -F 'classes=[{"class":"invoice","description":"Commercial bill with line items and totals"},{"class":"bank_statement","description":"Monthly summary of account transactions"}]' \
  -F 'model=classify-latest'

The response lists one class per page. Classify pages are 0-indexed (v1 convention); v2 Parse options.pages is 1-indexed, so add 1 when routing pages. Unmatched pages come back as unknown with a suggested_class. Response fields: ade-classify-response.

Section: Table of Contents Generation

Generates a hierarchical table of contents. Requires v1 Parse output (it depends on the anchor tags only v1 Parse emits); do not feed it v2 Markdown. Guide: https://docs.landing.ai/ade/ade-section. API reference: ade-section.

bashCopy code
curl -X POST 'https://api.va.landing.ai/v1/ade/section' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'markdown=@v1-parse-output.md' \
  -F 'model=section-latest'

An optional guidelines field steers the hierarchy. Each entry has title, level, section_number, and start_reference (the v1 chunk id where the section begins). Response fields: ade-section-response.

Build Extract Schema: Schema Generation

Generates or refines a JSON extraction schema from sample Markdown and/or a prompt; the returned schema string passes directly to either Extract API. Guide: https://docs.landing.ai/ade/ade-extract-schema-api. API reference: ade-build-extract-schema.

bashCopy code
curl -X POST 'https://api.va.landing.ai/v1/ade/extract/build-schema' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'markdowns=@sample.md' \
  -F 'model=extract-latest' \
  -F 'prompt=Extract the vendor name, invoice date, and total amount due'

Split: Multi-Document Separation

Classifies and separates a file containing multiple documents (for example, a scanned packet of invoices and receipts). Runs on v1 Parse output (parse with split=page first). Guide: https://docs.landing.ai/ade/ade-split. API reference: ade-split.

bashCopy code
curl -X POST 'https://api.va.landing.ai/v1/ade/split' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'markdown=@v1-parse-output.md' \
  -F 'split_class=[{"name":"Bank Statement","description":"Summary of account activity over a period"},{"name":"Pay Stub","description":"Earnings and deductions for one pay period","identifier":"Pay Stub Date"}]' \
  -F 'model=split-latest'

A next-generation Split v2 API is in Preview (select partners; accepts Markdown from either Parse version): https://docs.landing.ai/splitv2/splitv2.

v1 Parse and Extract (Superseded)

Still required for spreadsheets (XLSX, CSV), legacy binary Office files (DOC, PPT), password-protected files, custom figure prompts, and Section/Split pipelines. Same auth; host api.va.landing.ai; parse model dpt-2-latest; v1 responses use a flat chunks list with 0-indexed pages and left/top/right/bottom boxes. Guides: v1 Parse, v1 Extract, v1 Parse Jobs, v1 Extract Jobs, password-protected files, custom figure prompts, chunk types, v1 JSON response. File format support per version: v2 file types, v1 file types.

Workflow Rules

These rules come from field experience building document pipelines. Follow them whenever you write pipeline code around ADE. Full working pipelines (batch processing, classify-then-extract, RAG ingestion with vector databases, database loading, visualization, Streamlit review UIs) live at https://github.com/landing-ai/ade-sample-projects; most samples still use the v1 APIs, so check which endpoints a sample calls before borrowing code.

Pre-Flight: Inspect Before You Code (mandatory)

Before writing any section-detection, heading-matching, or text-search code:

1. Render 1 or 2 pages as PNG and read them as images. Check: handwriting or scan versus digital text, single versus two-column layout, running headers or watermarks, whether headings are styled text or plain bold.
2. Run one diagnostic parse on one sample and inspect the Markdown head plus a block inventory (type, page, box, first characters of each block). Heading format is document-specific and cannot be inferred from the task description: Introduction may appear as 1. Introduction (plain text), ## Introduction, or INTRODUCTION inside a larger text block. Getting this wrong causes a silent zero-match failure.
3. Cache parse output (save the response JSON) and reuse it while developing; re-parse only when the document set changes. Parse 1 to 3 samples during development, never the full corpus.

If heading formats vary across documents, match sections with an Extract call instead of regex.

Bounding-Box Work: Verify Visually (mandatory)

For any crop, overlay, or highlight built from grounding boxes:

• v2 grounding.page is 1-indexed; page renderers (such as PyMuPDF) are 0-indexed, so the renderer index is page - 1. An off-by-one lands the crop on an adjacent page.
• Boxes are normalized; multiply by the rendered page's pixel dimensions, not the PDF point size.
• After producing the first output image, read it back as an image and describe what you see. Compare against the request (asked for a table, got a chart? wrong page?). Only proceed with the remaining crops after the first is verified. A brightness heuristic cannot catch wrong-page bugs; visual inspection can.

Multi-Page Tables (Stitching)

ADE may emit a table that spans pages as separate table blocks per page, and any page's rows may come back as plain text instead of a table block, not just the last page. Three approaches, in order of robustness:

1. Parse, then Extract with a row schema (an array-of-objects field): the extract model reads the full Markdown, so it absorbs format inconsistencies. Two API calls; use this by default.
2. Parse the HTML tables from the Markdown: one call, but fragile; requires uniform row structure and breaks silently if you switch tables to pipe syntax.
3. pandas.read_html on the Markdown: quick prototyping only; misses rows that were emitted as plain text.

After stitching, validate with domain checks: column totals match a stated total, running balances reconcile, dates are chronological, row counts match a stated count. These catch merge errors that no parser will flag.

Classify-Then-Extract (Mixed Document Batches)

• Each file is one document of unknown type: run a one-field Extract (an enum type field) on the parsed Markdown, then extract again with the type-specific schema.
• One file contains several documents: use the v1 Split pipeline (v1 Parse with split=page, then Split, then Extract per sub-document).
• Route pages before parsing: use Classify on the raw file, then parse only the relevant pages with v2 options.pages (remember the 0-indexed to 1-indexed conversion).

RAG and Embedding Granularity

Choose the embedding unit to match retrieval needs; ADE blocks are the finest unit but not always the right one:

Embed text, table, and card blocks; exclude marginalia (running headers, footers, page numbers). Carry grounding metadata (source file, page, box coordinates) into the vector store as columns so every retrieval hit traces back to a document location.

Schema Design

• Start small (a few fields), then grow. Use descriptive field names and put format hints in descriptions ("in USD", "as YYYY-MM-DD"); descriptions act as extraction prompts.
• Keep nesting to one level of objects; use an array of objects for line items and transactions.
• v2 Extract silently removes unsupported JSON Schema keywords (allOf, oneOf, const, pattern, maximum, and others) instead of erroring; v1 Extract errors on them. Setting strict=true on v2 turns the silent removal into an HTTP 422. All fields are treated as required and nullable regardless of required.
• Schema authoring reference: https://docs.landing.ai/dpt3/ade-extract-schema-json. Or generate a starting schema with the Build Extract Schema API above.

Batch Processing and Scale

• Batches run as standard jobs. Create every job first, record the job_ids, then wait on each; a create-then-wait loop per document serializes the batch on its slowest job.
• If you do fan out over sync endpoints, keep concurrency modest (single digits) and retry 429/5xx with exponential backoff, except a 429 on one oversized document, which no retry clears (see Processing Modes). Limits: https://docs.landing.ai/dpt3/rate-limits.
• A sync request that times out (HTTP 504) means the document is too large for sync; resubmit it as a job rather than retrying.
• Save every parse response to disk as you go; a re-run should never re-parse documents that already succeeded.

Links

Guides:

• v2 overview: https://docs.landing.ai/dpt3/overview
• v2 quickstart: https://docs.landing.ai/dpt3/quickstart
• Parsing models (DPT-3 Pro vs. DPT-3 Verity): https://docs.landing.ai/dpt3/parse-models
• Ground extracted fields: https://docs.landing.ai/dpt3/ground
• Zero Data Retention: https://docs.landing.ai/ade/zdr
• Webhooks (job completion events): https://docs.landing.ai/dpt3/webhooks
• Migration guide (v1 to v2): https://docs.landing.ai/dpt3/migration-guide
• Rate limits: https://docs.landing.ai/dpt3/rate-limits
• Credit consumption: https://docs.landing.ai/dpt3/credit-consumption

API reference (full contracts, with cURL/Python/Node tabs):

• Parse v2: https://docs.landing.ai/api-reference/parse/ade-parse
• Parse Jobs v2: https://docs.landing.ai/api-reference/parse/ade-parse-jobs
• Extract v2: https://docs.landing.ai/api-reference/extract/ade-extract
• Extract Jobs v2: https://docs.landing.ai/api-reference/extract/ade-extract-jobs
• Ground v2: https://docs.landing.ai/api-reference/ground/ade-ground
• Classify: https://docs.landing.ai/api-reference/tools/ade-classify
• Section: https://docs.landing.ai/api-reference/tools/ade-section
• Build Extract Schema: https://docs.landing.ai/api-reference/tools/ade-build-extract-schema
• Split: https://docs.landing.ai/api-reference/tools/ade-split
• Parse v1: https://docs.landing.ai/api-reference/tools/ade-parse
• Extract v1: https://docs.landing.ai/api-reference/tools/ade-extract

Troubleshooting (per endpoint):

• Parse v2: https://docs.landing.ai/dpt3/parse-troubleshoot
• Extract v2: https://docs.landing.ai/dpt3/extract-troubleshoot
• Ground v2: https://docs.landing.ai/dpt3/ground-troubleshoot
• Classify: https://docs.landing.ai/ade/ade-classify-troubleshoot
• Section: https://docs.landing.ai/ade/ade-section-troubleshoot
• Split: https://docs.landing.ai/ade/ade-split-troubleshoot

Libraries:

• Python guide (v2): https://docs.landing.ai/dpt3/ade-python
• ade-python source: https://github.com/landing-ai/ade-python
• TypeScript guide (v2): https://docs.landing.ai/dpt3/ade-typescript
• ade-typescript source: https://github.com/landing-ai/ade-typescript