Convert Documents

Convert documents to structured JSON with Docutray's AI-powered OCR — pass a file and a document-type code, with multi-language SDK and REST examples.

The Convert operation extracts structured data from documents using AI-powered OCR. You provide a document (image or PDF) and a document type code, and DocuTray returns the extracted fields as JSON according to the document type's schema.

Quick Start

from pathlib import Path
from docutray import Client

client = Client(api_key="YOUR_API_KEY")

result = client.convert.run(
    file=Path("invoice.pdf"),
    document_type_code="invoice"
)

print(result.data)

Response

# result is a ConversionResult
print(result.data)
# {
#     "invoice_number": "F-2024-001",
#     "issue_date": "2024-01-15",
#     "vendor_name": "Acme Corporation",
#     "subtotal": 1000,
#     "tax": 160,
#     "total": 1160
# }

Async Conversion

For large documents or batch processing, use async conversion. The document is processed in the background and you can poll for the result.

# Start async conversion
status = client.convert.run_async(
    file=Path("large_document.pdf"),
    document_type_code="invoice"
)

print(f"Conversion ID: {status.conversion_id}")
print(f"Status: {status.status}")  # ENQUEUED

# Wait for completion (polls automatically)
result = status.wait()

if result.is_success():
    print(result.data)
elif result.is_error():
    print(f"Error: {result.error}")

Checking Status Manually

You can also check the status of an async conversion by its ID:

status = client.convert.get_status("cm5vm9hx30001m5cgh0p9v8qa")

if status.is_success():
    print(status.data)

Input Methods

DocuTray supports three methods for providing documents.

File Upload

Upload a file directly from disk or memory.

from pathlib import Path

# From a file path
result = client.convert.run(
    file=Path("invoice.pdf"),
    document_type_code="invoice"
)

# From bytes
with open("invoice.pdf", "rb") as f:
    result = client.convert.run(
        file=f.read(),
        document_type_code="invoice",
        content_type="application/pdf"
    )

# From a file object
with open("invoice.pdf", "rb") as f:
    result = client.convert.run(
        file=f,
        document_type_code="invoice"
    )

URL

Provide a publicly accessible URL to the document. DocuTray will download and process it.

result = client.convert.run(
    url="https://example.com/invoice.pdf",
    document_type_code="invoice"
)

Base64

Send a base64-encoded document in the request body.

import base64

with open("invoice.pdf", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()

result = client.convert.run(
    file_base64=encoded,
    document_type_code="invoice",
    content_type="application/pdf"
)

Document Metadata

You can attach custom metadata to any conversion. This metadata is returned in status responses and webhooks, useful for tracking your internal references.

result = client.convert.run(
    file=Path("invoice.pdf"),
    document_type_code="invoice",
    document_metadata={"customer_id": "cust_123", "batch": "2024-Q1"}
)

Parameters

Parameter	Type	Required	Description
`document_type_code`	string	Yes	Code identifying the document type schema to use
`file`	File	No	File to process (path, bytes, or file object)
`url`	string	No	Public URL of the document to download and process
`file_base64` / `base64`	string	No	Base64-encoded document content
`content_type`	string	No	MIME type of the document (auto-detected if not provided)
`document_metadata`	object	No	Custom metadata to attach to the conversion

You must provide exactly one of file, url, or file_base64/base64.

Supported file formats: JPEG, PNG, GIF, BMP, WebP, PDF (up to 100MB)

Error Handling

from docutray import (
    AuthenticationError,
    BadRequestError,
    RateLimitError,
    NotFoundError,
    DocuTrayError,
)

try:
    result = client.convert.run(
        file=Path("invoice.pdf"),
        document_type_code="invoice"
    )
except AuthenticationError:
    print("Invalid API key")
except BadRequestError as e:
    print(f"Invalid request: {e.message}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except NotFoundError:
    print("Document type not found")
except DocuTrayError as e:
    print(f"Error: {e.message}")

Complete Code

End-to-end example that converts a document with error handling and result processing.

from pathlib import Path
from docutray import Client, AuthenticationError, RateLimitError, DocuTrayError

client = Client(api_key="YOUR_API_KEY")

try:
    # Sync conversion for small documents
    result = client.convert.run(
        file=Path("invoice.pdf"),
        document_type_code="invoice",
        document_metadata={"source": "email", "batch": "2024-Q1"}
    )

    # Access extracted data
    data = result.data
    print(f"Invoice: {data.get('invoice_number')}")
    print(f"Total: ${data.get('total')}")

except AuthenticationError:
    print("Check your API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except DocuTrayError as e:
    print(f"Conversion failed: {e.message}")
finally:
    client.close()

SDK Reference

For detailed class and method documentation:

Convert Documents

On this page