Skip to content

Invoice with line items

A parse → extract → validate graph. The invoice has a table of lines; the rule checks that the amounts add up to the total, so a mistyped total is flagged instead of trusted.

The documents are synthetic (invented names, amounts and accounts), generated by scripts/docs_examples.py:

The graph

parse → extract
extract → validate

The full version body (graph and schemas), as the API takes it:

{
  "graph": {
    "nodes": [
      {
        "id": "parse",
        "type": "parse"
      },
      {
        "id": "extract",
        "type": "extract",
        "config": {
          "schema_id": "invoice"
        }
      },
      {
        "id": "validate",
        "type": "validate",
        "config": {
          "rules": [
            {
              "id": "lines_add_up",
              "kind": "deterministic",
              "severity": "error",
              "blocking": true,
              "check": {
                "type": "arithmetic",
                "operands": [
                  "line_items[*].amount"
                ],
                "operator": "sum",
                "equals": "total"
              }
            }
          ]
        }
      }
    ],
    "edges": [
      {
        "source": "parse",
        "target": "extract"
      },
      {
        "source": "extract",
        "target": "validate"
      }
    ]
  },
  "schemas": {
    "invoice": {
      "type": "object",
      "x-dx": {
        "document_type": "invoice"
      },
      "properties": {
        "invoice_number": {
          "type": "string",
          "x-dx": {
            "evidence": "required"
          }
        },
        "issue_date": {
          "type": "string",
          "format": "date"
        },
        "currency": {
          "type": "string",
          "enum": [
            "EUR",
            "USD",
            "GBP"
          ]
        },
        "supplier_name": {
          "type": "string"
        },
        "total": {
          "type": "number"
        },
        "line_items": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "description": {
                "type": "string"
              },
              "quantity": {
                "type": "number"
              },
              "unit_price": {
                "type": "number"
              },
              "amount": {
                "type": "number"
              }
            }
          }
        }
      }
    }
  }
}

Create it and run it

Set DX_BASE_URL and DX_API_KEY (see the quickstart), cd to docs/examples/gallery/invoice/ and run any of the three. They do the same.

Python

# SPDX-License-Identifier: Apache-2.0
# expect: "status": "succeeded"
"""Invoice with line items: create the workflow, run it on the document and print what comes back."""

import json
import os
import secrets
from pathlib import Path

import httpx

api = httpx.Client(
    base_url=os.environ["DX_BASE_URL"],
    headers={"Authorization": f"Bearer {os.environ['DX_API_KEY']}"},
    timeout=120,
)
name = f"invoice-{secrets.token_hex(3)}"  # unique, so the example can run again

# 1. Create the workflow, add the version (graph + schemas), publish it, point `prod` at it.
workflow = api.post("/v1/workflows", json={"name": name}).raise_for_status().json()
version = (
    api.post(
        f"/v1/workflows/{workflow['id']}/versions",
        json=json.loads(Path("workflow.json").read_text()),
    )
    .raise_for_status()
    .json()
)
api.post(f"/v1/workflow-versions/{version['id']}:publish", json={}).raise_for_status()
api.put(
    f"/v1/workflows/{workflow['id']}/aliases/prod", json={"version_id": version["id"]}
).raise_for_status()

# 2. Run it on the document and wait for the result.
run = (
    api.post(
        "/v1/runs",
        data={"workflow": f"{name}@prod"},
        files=[("files", ("invoice.pdf", Path("invoice.pdf").read_bytes(), "application/pdf"))],
    )
    .raise_for_status()
    .json()
)
run = api.get(f"/v1/runs/{run['id']}", params={"wait": 60}).raise_for_status().json()
result = api.get(f"/v1/runs/{run['id']}/result").raise_for_status().json()

node = result["outputs"]["extractions"]["extract"]
view = {
    "status": run["status"],
    "data": node["data"],
    "citations": [
        {"path": f["path"], "page": f["evidence"][0]["page"], "quote": f["evidence"][0]["quote"]}
        for f in node["fields"]
        if f["evidence"] and "[" not in f["path"]
    ],
    "checks": [
        {"rule": v["rule_id"], "status": v["status"]}
        for v in result["outputs"]["validations"]["validate"]
    ],
}
print(json.dumps(view, indent=2))

TypeScript

// SPDX-License-Identifier: Apache-2.0
// expect: "status": "succeeded"
// Invoice with line items: create the workflow, run it on the document and print what comes back.
// Node 22+: node --experimental-strip-types create.ts
import { readFileSync } from "node:fs";

const base = process.env.DX_BASE_URL as string;
const auth = { Authorization: `Bearer ${process.env.DX_API_KEY}` };
const name = `invoice-${Math.random().toString(16).slice(2, 8)}`; // unique, so it can run again

async function call(path: string, init: RequestInit = {}): Promise<any> {
  const response = await fetch(base + path, { ...init, headers: { ...auth, ...init.headers } });
  if (!response.ok) throw new Error(`${response.status} ${path}: ${await response.text()}`);
  return response.json();
}
const json = (body: unknown): RequestInit => ({
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(body),
});

// 1. Create the workflow, add the version (graph + schemas), publish it, point `prod` at it.
const workflow = await call("/v1/workflows", json({ name }));
const version = await call(
  `/v1/workflows/${workflow.id}/versions`,
  json(JSON.parse(readFileSync("workflow.json", "utf8"))),
);
await call(`/v1/workflow-versions/${version.id}:publish`, json({}));
await call(`/v1/workflows/${workflow.id}/aliases/prod`, {
  ...json({ version_id: version.id }),
  method: "PUT",
});

// 2. Run it on the document and wait for the result.
const form = new FormData();
form.append("workflow", `${name}@prod`);
form.append("files", new Blob([readFileSync("invoice.pdf")], { type: "application/pdf" }), "invoice.pdf");
const started = await call("/v1/runs", { method: "POST", body: form });
const run = await call(`/v1/runs/${started.id}?wait=60`);
const result = await call(`/v1/runs/${run.id}/result`);

const node = result.outputs.extractions["extract"];
const view = {
  status: run.status,
  data: node.data,
  citations: node.fields
    .filter((f: any) => f.evidence.length > 0 && !f.path.includes("["))
    .map((f: any) => ({ path: f.path, page: f.evidence[0].page, quote: f.evidence[0].quote })),
  checks: result.outputs.validations["validate"].map((v: any) => ({
    rule: v.rule_id,
    status: v.status,
  })),
};
console.log(JSON.stringify(view, null, 2));

curl

#!/usr/bin/env bash
# SPDX-License-Identifier: Apache-2.0
# expect: "status": "succeeded"
# Invoice with line items: create the workflow, run it on the document and print what comes back.
# Needs curl and jq; DX_BASE_URL and DX_API_KEY in the environment.
set -euo pipefail
api() { curl -sS --fail-with-body -H "Authorization: Bearer $DX_API_KEY" "$@"; }
JSON='Content-Type: application/json'
NAME="invoice-$RANDOM$RANDOM"  # unique, so the example can run again

# 1. Create the workflow, add the version (graph + schemas), publish it, point `prod` at it.
WORKFLOW=$(api -X POST "$DX_BASE_URL/v1/workflows" -H "$JSON" -d "{\"name\": \"$NAME\"}" | jq -r .id)
VERSION=$(api -X POST "$DX_BASE_URL/v1/workflows/$WORKFLOW/versions" -H "$JSON" -d @workflow.json | jq -r .id)
api -X POST "$DX_BASE_URL/v1/workflow-versions/$VERSION:publish" -H "$JSON" -d '{}' > /dev/null
api -X PUT "$DX_BASE_URL/v1/workflows/$WORKFLOW/aliases/prod" -H "$JSON" \
  -d "{\"version_id\": \"$VERSION\"}" > /dev/null

# 2. Run it on the document and wait for the result.
RUN=$(api -X POST "$DX_BASE_URL/v1/runs" -F "workflow=$NAME@prod" -F "[email protected]" | jq -r .id)
STATUS=$(api "$DX_BASE_URL/v1/runs/$RUN?wait=60" | jq -r .status)
api "$DX_BASE_URL/v1/runs/$RUN/result" | jq --arg status "$STATUS" '{status: $status, data: .outputs.extractions["extract"].data, citations: [.outputs.extractions["extract"].fields[] | select((.evidence | length) > 0 and (.path | contains("[") | not)) | {path, page: .evidence[0].page, quote: .evidence[0].quote}], checks: [.outputs.validations["validate"][] | {rule: .rule_id, status}]}'

Response

Produced by running the script above against a server with the fake model and these documents; make docs runs all the examples again and fails if an answer changes.

{
  "status": "succeeded",
  "data": {
    "currency": "EUR",
    "invoice_number": "INV-2026-0042",
    "issue_date": "2026-03-15",
    "line_items": [
      {
        "amount": 125,
        "description": "Steel bracket 40mm",
        "quantity": 10,
        "unit_price": 12.5
      },
      {
        "amount": 152,
        "description": "Aluminium rail 2m",
        "quantity": 4,
        "unit_price": 38
      },
      {
        "amount": 80,
        "description": "Fixing kit",
        "quantity": 25,
        "unit_price": 3.2
      },
      {
        "amount": 15,
        "description": "Packaging",
        "quantity": 1,
        "unit_price": 15
      }
    ],
    "supplier_name": "Northwind Components Ltd",
    "total": 372
  },
  "citations": [
    {
      "path": "currency",
      "page": 1,
      "quote": "EUR"
    },
    {
      "path": "invoice_number",
      "page": 1,
      "quote": "INV-2026-0042"
    },
    {
      "path": "issue_date",
      "page": 1,
      "quote": "2026-03-15"
    },
    {
      "path": "supplier_name",
      "page": 1,
      "quote": "Northwind Components Ltd"
    },
    {
      "path": "total",
      "page": 1,
      "quote": "372.00"
    }
  ],
  "checks": [
    {
      "rule": "lines_add_up",
      "status": "pass"
    }
  ]
}