Introduction

UiForm solves three major challenges in document processing with LLMs:

1. Universal Document Processing: Convert any file type (PDFs, Excel, emails, etc.) into LLM-ready format without writing custom parsers
2. Structured, Schema-driven Extraction: Get consistent, reliable outputs using schema-based prompt engineering
3. Automations: Create custom mailboxes and links to process documents at scale

We see it as building Stripe for document processing.

Our goal is to make the process of analyzing documents and unstructured data as easy and transparent as possible.

Many people haven’t yet realized how powerful LLMs have become at document processing tasks - we’re here to help unlock these capabilities.

​

How it works

UiForm allows you to easily create document processing automations. Here is the general workflow:

​

General philosophy

Our goal is to :

We currently support OpenAI, Anthropic, Gemini and xAI models.

You come with your own API key from your favorite AI provider, and we handle the rest.

​

Quickstart

​

Step 1: Setup the Python SDK

To get started, install the uiform package using pip:

pip install uiform

Then, create your API key on uiform.com and populate your env variables:

UIFORM_API_KEY=sk_xxxxxxxxx # Create your API key on https://www.uiform.com

Then, as we will use your API key to make requests to OpenAI on your behalf within an automation, you need to store your API key in the UiForm secrets manager:

import uiform
import os

uiclient = uiform.UiForm()

uiclient.secrets.external_api_keys.create(
    provider="OpenAI", 
    api_key=os.getenv("OPENAI_API_KEY")
)

Process your first document

Here is how to process your first document with the create_messages method:

from uiform import UiForm
from openai import OpenAI

# Initialize UiForm client
uiclient = UiForm()

# Convert any document into LLM-ready format
doc_msg = uiclient.documents.create_messages(
    document = "invoice.pdf"  # Works with PDFs, Excel, emails, etc.
)

client = OpenAI()
completion = client.chat.completions.create(
    model="gpt-4o-mini-2024-07-18",
    messages=doc_msg.openai_messages + [
        {
            "role": "user",
            "content": "Summarize the document"
        }
    ]
)

​

Step 2 : Create your JSON Schema

We use a standard JSON Schema with custom annotations (X-SystemPrompt, X-FieldPrompt, and X-ReasoningPrompt) as a prompt-engineering framework for the extraction process.

These annotations help guide the LLM’s behavior and improve extraction accuracy. You can learn more about these in our JSON Schema documentation.

from uiform import UiForm
from openai import OpenAI
from pydantic import BaseModel, Field, ConfigDict

# Define your extraction schema
class Invoice(BaseModel):
    model_config = ConfigDict(
        json_schema_extra = {
            "X-SystemPrompt": "You are an expert at analyzing invoice documents."
        }
    )
    
    total_amount: float = Field(...,
        description="The total invoice amount",
        json_schema_extra={
            "X-FieldPrompt": "Find the final total amount including taxes"
        }
    )
    date: str = Field(...,
        description="Invoice date in YYYY-MM-DD format",
        json_schema_extra={
            "X-ReasoningPrompt": "Look for dates labeled as 'Invoice Date', 'Date', etc."
        }
    )

# Process document and extract data
uiclient = UiForm()
doc_msg = uiclient.documents.create_messages(
    document = "invoice.pdf"
)
schema_obj = uiclient.schemas.load(
    pydantic_model = Invoice
)

# Extract structured data with any LLM
client = OpenAI()
completion = client.beta.chat.completions.parse(
    model="gpt-4o",
    messages=schema_obj.openai_messages + doc_msg.openai_messages,
    response_format=schema_obj.inference_pydantic_model
)

print("Extracted data:", completion.choices[0].message.parsed)

# Validate the response against the original schema if you want to remove the reasoning fields
from uiform._utils.json_schema import filter_reasoning_fields_json
assert completion.choices[0].message.content is not None
extraction = schema_obj.pydantic_model.model_validate(
    filter_reasoning_fields_json(completion.choices[0].message.content, schema_obj.pydantic_model)
)

​

Step 3: Create your FastAPI server with a webhook

Next, set up a FastAPI route that will handle incoming webhook POST requests. Below is an example of a simple FastAPI application with a webhook endpoint:

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from uiform.types.automations.webhooks import WebhookRequest
from pydantic import BaseModel, Field, ConfigDict

app = FastAPI()

@app.post("/webhook")
async def webhook(request: WebhookRequest):
    invoice_object = request.completion.choices[0].message.parsed # The parsed object is the same Invoice object as the one you defined in the Pydantic model
    print("Received payload:", invoice_object)
    return JSONResponse(content={"status": "success", "data": invoice_object})

# To run the FastAPI app locally, use the command:
# uvicorn your_module_name:app --reload
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

You can test the webhook endpoint locally with a tool like curl or Postman. For example, using curl:

curl -X POST "http://localhost:8000/webhook" \
     -H "Content-Type: application/json" \
     -d '{"name": "Team Meeting", "date": "2023-12-31"}'

​

Step 4: Create your automation

Finally, integrate the webhook with your automation system using the uiform client. This example demonstrates how to create an automation that triggers the webhook when a matching event occurs:

from uiform import UiForm

# Initialize the UiForm client
uiclient = UiForm()

# Create an automation that uses the webhook URL from Step 2
automation = uiclient.automations.mailboxes.create(
    email="invoices@mailbox.uiform.com",
    model="gpt-4o-mini",
    json_schema=Invoice.model_json_schema(), # use the pydantic model to create the json schema
    webhook_url="https://your-server.com/webhook",  # Replace with your actual webhook URL
)

At any email sent to invoices@mailbox.uiform.com, the automation will send a POST request to your FastAPI webhook endpoint, where the payload can be processed.

You can see the automation you just created on your dashboard !

​

Step 5: Test your automation

Finally, you can test the automation rapidly with the test functions of the sdk:

from uiform import UiForm

# Initialize the UiForm client
uiclient = UiForm()

# If you just want to send a test request to your webhook
log = uiclient.automations.mailboxes.tests.webhook(
    email="test-mailbox-local@devmail.uiform.com", 
)

# If you want to test the file processing logic: 
log = uiclient.automations.mailboxes.tests.process(
    email="test-mailbox-local@devmail.uiform.com", 
    document="your_invoice_email.eml"
)

# If you want to test a full email forwarding
log = uiclient.automations.mailboxes.tests.forward(
    email="uiform-quickstart@mailbox.uiform.com", 
    document="your_invoice_email.eml"
)

from uiform import UiForm

uiclient = UiForm()

# If you just want to send a test request to your webhook
log = uiclient.automations.mailboxes.tests.webhook(
    email="test-mailbox-local@devmail.uiform.com", 
    webhook_url="http://localhost:8000/webhook" # If you want to try your webhook locally, you can override the webhook url set in the automation
)

That’s it! You can start processing documents at scale. You have 1000 free requests to get started, and you can subscribe to the pro plan to get more.

But this minimalistic example is just the beginning. Continue reading to learn more about how to use UiForm to its full potential.

​

Go further

• Prompt Engineering Guide
• General Concepts
• Create mailboxes
• Create links
• Finetuning (coming soon)
• Prompt optimization (coming soon)
• Data-Labelling with our AI-powered annotator (coming soon)

​

Jupyter Notebooks

You can view minimal notebooks that demonstrate how to use UiForm to process documents:

• Mailbox creation quickstart
• Upload Links creation quickstart
• Document Extractions quickstart
• Document Extractions quickstart - Async

​

Community

Let’s create the future of document processing together!

Join our discord community to share tips, discuss best practices, and showcase what you build. Or just tweet at us.

We can’t wait to see how you’ll use UiForm.

• Discord
• Twitter

​

Roadmap

We share our roadmap publicly on Github

Among the features we’re working on:

[ ] Node.js SDK [ ] Finetuning [ ] Prompt optimization [ ] Data-Labelling platform