Metadata-Version: 2.4
Name: invoicedataextraction-sdk
Version: 0.4.0
Summary: Official Python SDK for Invoice Data Extraction.
Author-email: Invoice Data Extraction <developers@invoicedataextraction.com>
License-Expression: MIT
Project-URL: Homepage, https://invoicedataextraction.com
Project-URL: Documentation, https://invoicedataextraction.com/docs
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# invoicedataextraction-sdk

Official Python SDK for [Invoice Data Extraction](https://invoicedataextraction.com). 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

```bash
pip install invoicedataextraction-sdk
```

## Quick Start

```python
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. 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](https://invoicedataextraction.com/dashboard?view=API). 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:

```python
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

```python
# 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 cancelled from the web app. See the [full docs](https://invoicedataextraction.com/sdk/python) for details.

## Documentation

- [Python SDK docs](https://invoicedataextraction.com/sdk/python) — full method reference, parameters, return shapes, and examples
- [REST API docs](https://invoicedataextraction.com/api) — endpoint-level documentation for direct HTTP integration
- [Dashboard](https://invoicedataextraction.com/dashboard?view=API) — manage API keys and view extraction results

## License

MIT
