StructOCR Python SDK

Official Python client for the StructOCR API.

Send a photo or PDF of a passport, ID card, driver license, VIN, invoice, receipt or shipping container and get structured JSON back: one method call per document, no templates to train.

The SDK accepts a local JPG, PNG, WebP, or PDF path, plus in-memory bytes. It validates the decoded file locally, converts it to Base64, and sends JSON as {"img": "..."}. The REST API also supports multipart uploads; this SDK release keeps Base64 JSON as its default transport for backward compatibility.

Get a free API key

1. Create an account. New accounts get 200 free credits, enough for 100 passport or driver license scans, and no credit card is needed.
2. Copy your key from API Keys in the dashboard.
3. Optionally try any document type on a sample image in the Playground before you write code.

Not ready to sign up? Try any document in your browser on a sample image or your own file, no account needed: use the Try it links in the table below.

After the free credits, packs start at $5 for 500 credits. There is no subscription and credits do not expire. See pricing.

Supported documents

The receipt endpoint's optional enhanced mode costs 2 credits. Only successful requests are charged.

Install

pip install --upgrade structocr

Python 3.7+ is required.

Quick start

export STRUCTOCR_API_KEY="YOUR_API_KEY"

from structocr import StructOCR

client = StructOCR()
result = client.scan_passport("./passport.jpg")

if result.get("success"):
    data = result["data"]
    print(data.get("passport_number"))
    print(data.get("given_names"), data.get("surname"))

A passport scan returns JSON like this (fictional sample document):

{
  "success": true,
  "data": {
    "type": "passport",
    "country_code": "UTO",
    "nationality": "UTOPIAN",
    "passport_number": "X4R7T2K9P",
    "surname": "MORGAN",
    "given_names": "OLIVIA ROSE",
    "sex": "F",
    "date_of_birth": "1990-03-14",
    "place_of_birth": "ZENITH CITY",
    "date_of_issue": "2024-07-16",
    "date_of_expiry": "2034-07-15",
    "place_of_issue": null
  }
}

PDF paths work the same way:

result = client.scan_invoice("./invoice.pdf")

FastAPI and other server frameworks can pass uploaded bytes without a temporary file:

content = await upload.read()
result = client.scan_passport(content)

Methods

scan_passport(file)
scan_national_id(file)
scan_driver_license(file)
scan_driver_license_pdf417(file)
scan_invoice(file)
scan_receipt(file)
scan_vin(file)
scan_hin(file)
scan_container(file)
scan_license_plate(file)
scan_vehicle_registration(file)
scan_atm_cassette(file)
scan_weighbridge_ticket(file)
get_account_balance()

All document methods accept a local path or bytes, up to 4.5MB. Most methods support JPG, PNG, WebP, and PDF. scan_driver_license_pdf417 accepts JPG, PNG, and WebP only.

The Receipt endpoint returns v2 by default. Enhanced accuracy costs 2 credits instead of the standard 1 credit and is enabled with the accuracy parameter:

receipt = client.scan_receipt(
    "./receipt.jpg",
    accuracy="enhanced",
)

response_version=2 remains accepted for compatibility but is not required. Receipt v1 is retired.

US driver license PDF417 example:

result = client.scan_driver_license_pdf417("./license-back.jpg")
if result.get("success"):
    print(result["data"]["document_number"])

Weighbridge ticket example:

result = client.scan_weighbridge_ticket("./weighbridge-ticket.jpg")
if result.get("success"):
    print(result["data"]["weights"])
    print(result["data"]["validation"])

Configuration

client = StructOCR(
    api_key="YOUR_API_KEY",
    base_url="https://api.structocr.com/v1",
    timeout=60,
)

See the API documentation for endpoint-specific response schemas and error codes.

Errors

API and network failures raise StructOCRError. Existing except RuntimeError code continues to work because StructOCRError extends RuntimeError.

from structocr import StructOCRError

try:
    client.scan_passport("./passport.jpg")
except StructOCRError as error:
    print(error.status_code, error.code, error.retryable)

retryable is advisory only. The SDK does not automatically retry OCR requests because doing so without an idempotency key could charge a request twice.

License

MIT