Extract structured document data

Extract turns business documents into structured JSON your ERP or ops workflow can consume. Unlike document Q&A chat, Extract returns typed fields (invoice numbers, receipt totals, PO line items, bank transactions) with confidence scores — not natural-language answers.

Availability: Dev environment (api.dev.oprag.ai) as of July 2026. Staging and production require enable_extract in infrastructure — until enabled, Extract routes are not mounted and return 404, not 503.

Schemas (v1): Thirteen built-in schemaId values — set one on POST /v1/extract/upload-urls (or omit / pass "auto" for auto-detect). Only the data shape in the poll response changes.

invoice · receipt · purchase_order · credit_note · delivery_note · bank_statement · payslip · utility_bill · ticket · tax_form · contract · gst_invoice · id_document (dev only — extracts PII; caller responsible for consent)

POST upload-urls → S3 presigned POST → POST confirm → Poll GET /jobs/{id} → Map JSON to your system

What you get (v1)

Step 1 — Get an integration key

Create or rotate a key under any project in your workspace (Project → API keys). Draft projects work — deploy is not required for Extract. Use sk_live_* or sk_test_*. Embed keys (embed_live_*, embed_test_*) do not work for Extract.

Step 2 — Reserve upload URL and start extraction

All files use the presigned upload flow. POST /v1/extract/jobs (direct multipart) returns 400 — do not use it.

export API_URL="https://api.dev.oprag.ai"
export OPRAG_KEY="sk_live_YOUR_KEY"

# 1) Reserve presigned URL + jobId (example: invoice)
RESP=$(curl -sS -X POST "$API_URL/v1/extract/upload-urls" \
  -H "X-Oprag-Key: $OPRAG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"document.pdf","contentType":"application/pdf","schemaId":"invoice","clientRef":"ap-001"}')
JOB_ID=$(echo "$RESP" | jq -r .jobId)
UPLOAD_URL=$(echo "$RESP" | jq -r .uploadUrl)

# 2) POST file to S3 (presigned form fields + file)
S3_ARGS=()
while IFS= read -r -d '' line; do
  S3_ARGS+=(-F "$line")
done < <(echo "$RESP" | jq -j '.uploadFields | to_entries[] | "\(.key)=\(.value)\u0000"')
curl -sS -X POST "$UPLOAD_URL" "${S3_ARGS[@]}" -F "file=@document.pdf"

# 3) Confirm → queue extraction
curl -sS -X POST "$API_URL/v1/extract/jobs/${JOB_ID}/confirm" \
  -H "X-Oprag-Key: $OPRAG_KEY"

Change schemaId in step 1 for other document types (receipt, purchase_order, bank_statement, gst_invoice, etc.). Same three steps for every schema.

Confirm returns 202 with status: "queued" and a relative pollUrl — prepend https://api.dev.oprag.ai.

Step 3 — Poll for results

curl "$API_URL/v1/extract/jobs/$JOB_ID" \
  -H "X-Oprag-Key: $OPRAG_KEY"

Poll every 2–5 seconds until status is completed or failed. While upload_pending, complete the S3 POST and confirm first.

When status is completed, read fields from data (shape depends on schemaId). On failed, check error.code (unsupported_format, password_protected, corrupt_file, timeout, extraction_failed).

Extract vs document Q&A

Use Extract for AP automation, expense receipts, procurement sync, credit memos, shipping docs, bank reconciliation, and contract field capture. Use chat when users ask questions about your knowledge base.

Full reference

• API docs — Extract section (schema catalog, limits, errors)
• Engineering quickstart: extract/docs/guides/extract-quickstart.md
• Schema field references: extract/docs/api/extract-*-schema.md (thirteen files under extract/docs/api/)

For document Q&A instead of extraction, see integrate document Q&A with REST.