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, waits until it finishes, and downloads the results. The returned result is the final status response from the API. For completed responses, check result["pages"]["failed_count"] to verify that all uploaded pages were processed successfully, and check result["review_needed"]["count"] for any extracted values that require human verification before relying on the extracted data.

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)

Working with the rows, and stopping a run

# The extracted rows as JSON, one page at a time or every row
page = client.get_results(extraction_id=extraction_id, limit=100)
for row in client.iterate_results(extraction_id=extraction_id):
    print(row["Invoice Number"], row["Total Amount"])

# Stop an extraction that is still queued or processing
client.cancel_extraction(extraction_id=extraction_id)

Values in the JSON output and in these rows are strings unless you submit with json_typed_values=True, when amounts and rates come back as numbers, yes/no fields as booleans and empty cells as None. The other per-extraction options on extract(...) and submit_extraction(...) are output_language, review_needed_fill_color, affected_field_fill_color and send_completion_email.

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 reaches a terminal state, extract(...) returns that response rather than raising — check result["status"] for "completed", "failed", or "cancelled" for tasks stopped from the web app or with cancel_extraction(...). 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