docpeel — Python SDK

Official Python SDK for the DocPeel document AI API. Extract structured JSON from invoices, receipts, contracts, IDs, bank statements, and any other document — in a few lines of Python.

Install

pip install docpeel

Requires Python 3.8+.

Quickstart

import base64
from docpeel import DocPeel

client = DocPeel(api_key="dpk_live_...")  # or set DOCPEEL_API_KEY env var

# DocPeel takes documents as base64 in a JSON body.
with open("invoice.pdf", "rb") as f:
    file_b64 = base64.b64encode(f.read()).decode("ascii")

extraction = client.extractions.create(
    file_b64=file_b64,
    file_name="invoice.pdf",
    template_id="tpl_invoice",  # optional
)

for f in extraction.fields:
    print(f.field, "=", f.value, f"({f.confidence}% confidence)")

# → Invoice Number = INV-2024-081 (98% confidence)
# → Total          = $1,240.00     (97% confidence)

Prefer to let the SDK encode for you? Pass a path, bytes, or a binary file-like as file and the SDK base64-encodes it before sending:

ext = client.extractions.create("invoice.pdf")  # path — SDK reads + encodes

Authentication

Pass your API key directly or set the DOCPEEL_API_KEY environment variable:

import os
os.environ["DOCPEEL_API_KEY"] = "dpk_live_..."
client = DocPeel()

Generate keys in your DocPeel dashboard.

API reference

client.ping()

Verify the API key. Returns a dict with key + workspace metadata.

me = client.ping()
# {'api_key': {'id': ..., 'name': ..., 'scopes': [...]}, 'request_id': ...}

client.extractions.create(file=None, *, file_b64=None, file_name=None, content_type=None, template_id=None)

Submit a document. Pass either:

• file_b64 — a pre-encoded base64 string (recommended; the SDK passes it through untouched). A data: URI prefix is allowed and stripped. Requires file_name.
• file — the SDK reads it, base64-encodes it, then sends it. Accepts:
  • A path (str or os.PathLike)
  • Raw bytes — requires file_name
  • A binary file-like object — e.g. open(path, "rb") / io.BytesIO

Either way the wire format is application/json with the body{' '} { "file": <base64>, "file_name": ..., "content_type": ..., "template_id": ... } — no multipart upload is ever sent.

Returns an Extraction dataclass.

import base64
with open("receipt.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode("ascii")
    ext = client.extractions.create(file_b64=b64, file_name="receipt.jpg")

client.extractions.retrieve(extraction_id)

ext = client.extractions.retrieve("ext_01HZX...")

Errors

All HTTP errors raise DocPeelError with .status, .code, .message, and .request_id:

from docpeel import DocPeel, DocPeelError

try:
    client.extractions.create("invoice.pdf")
except DocPeelError as err:
    if err.code == "rate_limited":
        time.sleep(1)
    else:
        raise

Configuration

client = DocPeel(
    api_key="dpk_live_...",
    base_url="https://api.docpeel.com",  # override for staging
    timeout=60,                          # seconds, default 120
)

To customise retries or adapters, pass your own requests.Session:

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=Retry(total=3, backoff_factor=0.5)))

client = DocPeel(api_key="dpk_live_...", session=session)

Documentation

• Full docs: https://docpeel.com/docs
• Python SDK guide: https://docpeel.com/docs/sdk/python
• REST API reference: https://docpeel.com/docs/api/endpoints

License

MIT