API Reference

The Deep-OCR API lets you extract structured data from any document with a single HTTP call. Submit a file with a document type to POST /v1/extractions, then poll the returned extraction id until it completes and read the typed JSON result. No configuration, no model training, no SDKs required.

# Authenticate every request with your Bearer API key (see Authentication below).

# 1 · Submit — returns 202 Accepted with an extraction id
curl -sS -X POST "https://api.deep-ocr.com/v1/extractions" \
  -F "file=@invoice.pdf" \
  -F "document_type=invoice"
# → { "id": "ext_123", "status": "queued" }

# 2 · Poll until completed (honour the Retry-After header)
curl -sS "https://api.deep-ocr.com/v1/extractions/ext_123"
# → { "status": "completed", "result": { … } }

All requests require an API key passed as a Bearer token in the Authorization header. You can create and manage keys in the Developer Center.

Authorization: Bearer deep_ocr_sk_live_xxxxxxxxxxxxxxxxxxxx

Submit a document for extraction. The endpoint accepts a multipart/form-data body and always replies 202 Accepted with an extraction whose id is ext_…. Poll that id until it reaches a terminal status and read the result field — see Poll for the result below.

Request Parameters

Code Examples

# Authenticate every request with your Bearer API key (see Authentication above).

# 1 · Submit the document — returns 202 Accepted with an extraction id
curl -sS -X POST "https://api.deep-ocr.com/v1/extractions" \
  -F "file=@invoice.pdf" \
  -F "document_type=invoice"
# → { "id": "ext_123", "status": "queued" }

# 2 · Poll until the status is terminal (honour the Retry-After header)
curl -sS "https://api.deep-ocr.com/v1/extractions/ext_123"
# → { "status": "completed", "result": { … } }

You'll get a 202 with an id — but not the data yet. Next: poll for the result →

Every document is processed as a background job. The POST /v1/extractions call always replies 202 Accepted with an extraction whose id is ext_… — never the result inline. Poll that id until it reaches a terminal status and read the result field.

Poll until the status is terminal

# Authenticate every request with your Bearer API key (see Authentication above).
# (You already have the id from the 202 response to Submit a document, above.)

curl -sS "https://api.deep-ocr.com/v1/extractions/ext_123"
# → { "status": "processing" }   (+ Retry-After: <seconds>)     # keep polling
# → { "status": "completed", "result": { … } }                  # success → read result
# → { "status": "failed",    "error":  { … } }                  # terminal failure

Polling contract

• Poll GET /v1/extractions/{id} with the same Authorization header. Non-terminal statuses (queued, processing) mean keep polling — wait the Retry-After header (seconds) the server returns.
• Success is gated on status === "completed" — not on HTTP 200. A failed extraction is returned as HTTP 200 carrying status: "failed", so always check the status before using the body.
• On a completed job the extracted data is under result — the shape shown under The result you get back below.

Parameters, limits & errors

• document_type is a required multipart form field — one of the 12: auto, invoice, receipt, contract, id_document, delivery_note, bank_statement, payslip, purchase_order, handwriting, generic, fulltext. Default to generic (cheap general schema); auto runs an extra classification pass and fulltext defaults to ×10 on public plans; overage-enabled custom plans may bill 1:1. Use metadata.pages_billed as the source of truth.
• Limits:up to ≈100 MB and ≈350 pages per document.
• A failed extraction carries { "error": { "code", "message" } } where code is one of: payload_too_large, unprocessable, quota_exceeded, too_many_inflight, not_found, too_many_pages, upstream_unavailable, expired, worker_failed.

Retention. A finished extraction stays retrievable (HTTP 200) for about 24 hours after it terminates; once that window elapses the id returns 404 (there is no 410). Re-submit the document if you need it again.

When an extraction completes, the extracted data is carried in its result field. The shape of that result is consistent across all document types:

Example — Invoice result

{
  "document_type": "invoice",
  "content": {
    "vendor": {
      "name": "ACME Solutions GmbH",
      "address": "123 Example Street, 10115 Berlin",
      "tax_id": "DE123456789",
      "email": "billing@acme.de",
      "phone": null
    },
    "customer": {
      "name": "Your Company Ltd.",
      "address": "42 High Street, 20354 Hamburg",
      "customer_number": "CUS-0042"
    },
    "invoice_number": "RE-2024-0815",
    "invoice_date": "2024-03-01",
    "due_date": "2024-03-31",
    "currency": "EUR",
    "line_items": [
      {
        "description": "Software License Q1/2024",
        "quantity": 1,
        "unit_price": 490.00,
        "total": 490.00,
        "tax_rate": 19
      }
    ],
    "subtotal": 490.00,
    "tax_breakdown": [
      { "rate": 19, "net_amount": 490.00, "tax_amount": 93.10 }
    ],
    "tax_amount": 93.10,
    "total": 583.10,
    "is_reverse_charge": false,
    "payment_terms": "14 days net",
    "bank_details": {
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX",
      "bank_name": "Commerzbank"
    },
    "is_paid": false,
    "notes": null,
    "items_truncated": false
  },
  "metadata": {
    "pages": 1,
    "pages_billed": 1,
    "processing_time": 1.84
  }
}

When you want the full readable text of a PDF or scanned document — including tables, headings, and structure — pass document_type=fulltext. The response shape stays the same except that content has exactly one key, markdown, holding the verbatim document text as Markdown. Headings, paragraphs, lists, and tables are preserved. Multi-page documents are joined with a \n\n<!-- page break -->\n\n sentinel so you can split visually if you want.

Request

# Authenticate every request with your Bearer API key (see Authentication above).

# 1 · Submit with document_type=fulltext — returns 202 Accepted
curl -sS -X POST "https://api.deep-ocr.com/v1/extractions" \
  -F "file=@contract.pdf" \
  -F "document_type=fulltext"
# → { "id": "ext_123", "status": "queued" }

# 2 · Poll until completed, then read result.content.markdown
curl -sS "https://api.deep-ocr.com/v1/extractions/ext_123"
# → { "status": "completed", "result": { "content": { "markdown": "# …" } } }

Example — Fulltext result

{
  "document_type": "fulltext",
  "content": {
    "markdown": "# Service Agreement\n\n## 1. Scope of Services\n\nThis Agreement governs the cooperation between Party A and Party B for the provision of consulting and implementation services as set out below.\n\n| Item | Description | Quantity |\n|---|---|---|\n| 1 | Consulting services | 10 h |\n| 2 | Implementation | 40 h |\n\n<!-- page break -->\n\n## 2. Fees\n\nThe total fee amounts to EUR 5,000, payable within 14 days of the invoice date."
  },
  "metadata": {
    "pages": 3,
    "pages_billed": 30,
    "processing_time": 7.42
  }
}

These are the schemas the result.content from step 3 conforms to — pick one as your document_type when you submit. Each document_type uses a pre-defined extraction schema. The returned content object always matches that schema — every field is present, unknown fields are null.

Monetary values are returned as numbers (e.g. 583.10) so they can be used directly in calculations — the currency is always available separately in the currency field as an ISO 4217 code (e.g. EUR). Dates are ISO 8601 YYYY-MM-DD. Every field not found in the document is returned as null.

{ "description": "Software License Q1/2024", "quantity": 1, "unit_price": 490.00, "total": 490.00, "tax_rate": 19 }

{ "rate": 19, "net_amount": 490.00, "tax_amount": 93.10 }

{ "description": "Oat Milk 1L", "quantity": 2, "unit_price": 1.49, "total": 2.98, "tax_rate": 7 }

{ "rate": 7, "net_amount": 2.80, "tax_amount": 0.20 }

{ "role": "service_provider", "name": "ACME Ltd.", "address": "123 Main St, London EC1A 1BB", "representative": "Jane Smith" }

["Provide IT consulting services 40 hours per week", "Pay monthly fee of €5,000 by the 15th"]

{ "party": "ACME GmbH", "signed_date": "2024-01-15", "signed_by": "Max Müller" }

{ "date": "2024-03-15", "value_date": "2024-03-15", "description": "Direct debit rent March", "reference": "INV-2024-03", "amount": -950.00, "type": "debit", "balance": 2340.12 }

{ "description": "Base salary", "amount": 3500.00 }

{ "description": "Income tax", "amount": 650.00 }

{ "position": 1, "description": "Laptop Dell XPS 15", "article_number": "DEL-XPS-15", "quantity": 2, "unit": "pcs", "unit_price": 1200.00, "total": 2400.00, "tax_rate": 19 }

There are two kinds of error. Transport errors — an invalid request, a missing key, or an unknown id — come back as the HTTP status codes below. A document that was accepted but could not be processed fails the extraction: the job reaches status: "failed" carrying { "error": { "code", "message" } } with the closed code set listed under Poll for the result (above).

Rate limits are enforced per API key. Exceeding the limit returns HTTP 429. Limits reset every minute.

Use Deep-OCR with the tools you already know — from no-code automation to AI-assisted development.