invoicedataextraction-sdk 0.2.0

Official Python SDK for Invoice Data Extraction.

invoicedataextraction-sdk

Official Python SDK for Invoice Data Extraction. Handles file upload, extraction submission, polling, and result download so you can go from local files to structured output in a few lines of code.

• Python 3.9 or later

Install

pip install invoicedataextraction-sdk

Quick Start

import json
import os
import sys

from invoicedataextraction import InvoiceDataExtraction
from invoicedataextraction.errors import SdkError, ApiResponseError

try:
    client = InvoiceDataExtraction(
        api_key=os.environ.get("INVOICE_DATA_EXTRACTION_API_KEY"),
    )

    result = client.extract(
        folder_path="./invoices",
        prompt="Extract invoice number and total",
        output_structure="per_invoice",
        download={
            "formats": ["xlsx", "json"],
            "output_path": "./output",
        },
        console_output=True,  # remove to disable console logging
    )
except (SdkError, ApiResponseError) as error:
    print(json.dumps(error.body, indent=2), file=sys.stderr)
    raise SystemExit(1)

extract(...) uploads your files (pass a folder_path or a list of files), submits the extraction, polls until it finishes, and downloads the results. The returned result is the final polling response from the API. Check result["pages"]["failed_count"] to verify that all uploaded pages were processed successfully.

Generate an API key from your dashboard. Every account includes 50 free pages per month. Additional credits can be purchased on a pay-as-you-go basis with no subscription needed.

Staged Workflow

If you need control over individual steps — for example, uploading files in one part of your system and extracting in another — use the lower-level methods:

import json
import os
import sys

from invoicedataextraction import InvoiceDataExtraction
from invoicedataextraction.errors import SdkError, ApiResponseError

try:
    client = InvoiceDataExtraction(
        api_key=os.environ.get("INVOICE_DATA_EXTRACTION_API_KEY"),
    )

    upload = client.upload_files(
        files=["./invoice1.pdf", "./invoice2.pdf"],
        console_output=True,
    )

    submitted = client.submit_extraction(
        upload_session_id=upload["upload_session_id"],
        file_ids=upload["file_ids"],
        prompt="Extract invoice number and total",
        output_structure="per_invoice",
    )

    result = client.wait_for_extraction_to_finish(
        extraction_id=submitted["extraction_id"],
        console_output=True,
    )

    client.download_output(
        extraction_id=submitted["extraction_id"],
        format="xlsx",
        file_path="./output/invoices.xlsx",
    )
except (SdkError, ApiResponseError) as error:
    print(json.dumps(error.body, indent=2), file=sys.stderr)
    raise SystemExit(1)

Listing past extractions

# One-page browse with filters
page = client.list_extractions(
    status="completed",
    limit=50,
)

# Auto-paginating iterator over every matching extraction
for extraction in client.iterate_extractions(status="completed"):
    print(extraction["extraction_id"], extraction["task_name"])

# Full record (the original prompt, options, full pages, full failure error, etc.)
result = client.get_extraction(extraction_id="...")
extraction = result["extraction"]

On listing methods, team admins can pass scope="team" to see extractions submitted by any team member; pass scope="own" to force own-only results.

Error Handling

SDK methods raise SdkError or ApiResponseError on failure. The structured error body is on error.body, with fields error.body["error"]["code"], error.body["error"]["message"], error.body["error"]["retryable"], and error.body["error"]["details"].

When an extraction task itself fails (e.g. insufficient credits), extract(...) returns the failed response rather than raising — check result["status"] for "completed" or "failed". See the full docs for details.

Documentation

• Python SDK docs — full method reference, parameters, return shapes, and examples
• REST API docs — endpoint-level documentation for direct HTTP integration
• Dashboard — manage API keys and view extraction results

License

MIT