API Reference

Deep-OCR extracts structured JSON from supported document types or full text as Markdown. Processing is asynchronous: submit a file with a document type to POST /v1/extractions, then poll for its status and retrieve the result when processing completes. You need an API key and an HTTP client; no SDK is 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. Accepted requests return 202 Accepted with an extraction ID beginning with ext_…. Poll that ID until processing completes or fails. For completed extractions, 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 processing completes or fails (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 returns, when the request is accepted, 202 Accepted with an extraction ID beginning with ext_… — processing continues in the background. Poll that ID until processing completes or fails. For completed extractions, read the result field.

Poll until processing completes or fails

# 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

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 selects the extraction format. Predefined structured types use a fixed schema; generic adapts to the document and fulltext returns Markdown. For predefined types, the returned content object follows the schema, with unavailable values represented as null.

Monetary values are returned as numbers (e.g. 583.10). When identified, the currency is provided separately in the currency field as an ISO 4217 code (e.g. EUR). Dates are ISO 8601 YYYY-MM-DD. For predefined structured types, unavailable field values are 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 a machine-readable code and a message describing the failure.

Document submission limits apply per API key and plan. Exceeding a limit returns HTTP 429. Polling has a separate allowance; follow Retry-After between polls. Additional protective limits may also apply.

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