canonical: https://jentic.com/apis/parsio.io/parsio

# Parsio Document Parser API

Jentic publishes the only available OpenAPI specification for Parsio API, keeping it validated and agent-ready. Parsio is an AI-powered document and email parser that extracts structured data from PDFs, emails, spreadsheets, and other documents. The API allows programmatic management of mailboxes, document upload for parsing, retrieval of parsed data, and webhook configuration for real-time data delivery, enabling automated document processing workflows.

## For AI agents

Extract structured data from PDFs, emails, and documents; manage parsing mailboxes, retrieve parsed results, and configure webhooks across 20 endpoints.

## Scope

Covers document upload, AI-powered parsing, parsed data retrieval, mailbox management, and webhook configuration. Does not handle document generation, OCR-only extraction, or batch processing outside mailbox workflows - use for structured data extraction from documents and emails only.

## Capabilities

- Create and manage email parsing mailboxes
- Upload documents (PDFs, spreadsheets) for AI-powered parsing
- Retrieve structured parsed data from documents and emails
- Configure parsing templates and field extraction rules
- Set up webhooks for real-time parsed data delivery
- List all mailboxes and their parsing configurations
- Query parsed documents by mailbox or date range
- Update mailbox settings including email prefixes and attachment handling
- Delete parsed documents and manage data retention
- Export parsed data in JSON format

## Use cases

### Automated Invoice Data Extraction

Extract line items, totals, vendor details, and dates from PDF invoices using AI-powered parsing. POST `/mailboxes/{mailbox_id}/documents` uploads invoice PDFs, then GET `/documents/{document_id}/parsed` retrieves structured JSON with extracted fields. Configure webhooks via POST `/mailboxes/{mailbox_id}/webhooks` to push parsed data directly to accounting systems.

Example prompt: POST `/mailboxes/{mailbox_id}/documents` with PDF, then GET `/documents/{document_id}/parsed` to retrieve extracted invoice fields

### Email Parsing and Lead Capture

Set up email parsing mailboxes that automatically extract structured data from incoming emails such as lead forms, order confirmations, or support tickets. GET /mailboxes lists all mailboxes with their parsing email addresses. Forward emails to the mailbox address, and Parsio extracts fields based on configured templates. Retrieve parsed data via GET `/mailboxes/{mailbox_id}/documents.`

Example prompt: GET /mailboxes to find parsing email address, forward emails to it, then GET `/mailboxes/{mailbox_id}/documents` to retrieve parsed data

### Real-Time Document Processing via Webhooks

Configure webhooks to receive parsed document data as soon as parsing completes, enabling real-time automation. POST `/mailboxes/{mailbox_id}/webhooks` sets up webhook URLs, and Parsio POSTs parsed JSON to your endpoint immediately after processing. Ideal for triggering downstream workflows in CRMs, ERPs, or automation platforms.

Example prompt: POST `/mailboxes/{mailbox_id}/webhooks` with endpoint URL, then receive parsed data via webhook POST requests

### AI-Driven Document Workflows via Jentic

An AI agent managing document workflows can upload invoices, parse order confirmations, extract table data from PDFs, and configure webhooks through Jentic without holding Parsio API keys in context. Jentic resolves intents like 'parse this invoice' to the correct Parsio upload and retrieval endpoints.

Example prompt: Search Jentic for 'parse a PDF document', load POST `/mailboxes/{mailbox_id}/documents` schema, execute upload, then retrieve parsed data

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/mailboxes` | List all parsing mailboxes |
| GET | `/mailboxes/{mailbox_id}` | Retrieve mailbox details and configuration |
| POST | `/mailboxes/{mailbox_id}/documents` | Upload a document for parsing |
| GET | `/mailboxes/{mailbox_id}/documents` | List all parsed documents in a mailbox |
| GET | `/documents/{document_id}/parsed` | Retrieve parsed structured data from a document |
| POST | `/mailboxes/{mailbox_id}/webhooks` | Configure a webhook for real-time data delivery |
| POST | `/mailboxes/{mailbox_id}` | Update mailbox settings |

## Key resources

- **Mailboxes** — Email parsing endpoints with configurable templates and extraction rules
- **Documents** — Uploaded or emailed documents with parsed structured data
- **Parsed Data** — Structured JSON output extracted from documents
- **Webhooks** — Real-time parsed data delivery endpoints
- **Templates** — Parsing field configuration and extraction rules

## Why Jentic

- **Setup:** Wiring the Parsio Document Parser API by hand means learning its X-API-Key header auth, setting the api.parsio.io host, and building multipart upload and result-polling handling yourself. Through Jentic you install once, import Parsio from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Parsio puts the mailbox id in the URL path (`/mailboxes/{mailbox_id}/...`), so a rule can pin your agent to one mailbox: it can upload documents and read parsed data for that mailbox and nothing else. You choose the operations it may call, so webhook configuration is not included unless you add it.
- **Credential handling:** Your Parsio X-API-Key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'parse a PDF invoice' or 'retrieve extracted email data', and Jentic returns the matching Parsio operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Mindee OCR API** — An OCR and document data extraction platform, offering an alternative to Parsio for turning documents, invoices, and receipts into structured data.
- **Cloud Document AI API** — Google Cloud's machine-learning document parsing and OCR service, a scalable alternative to Parsio for extracting structured data from documents.

## FAQ

### Why is there no official OpenAPI spec for Parsio API?

Parsio publishes API documentation at https://help.parsio.io/public-api but not a structured OpenAPI specification. Jentic generates and maintains this spec based on Parsio's documentation so that AI agents and developers can call Parsio API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Parsio API use?

The Parsio API uses API key authentication passed in the X-API-Key header. Retrieve your API key from your Parsio account settings. Through Jentic, the key lives in the encrypted vault and is injected at execution time so it never enters agent context.

### What document types can Parsio parse?

Parsio can parse PDFs, emails (plain text and HTML), spreadsheets (CSV, Excel), and images (via OCR). The API accepts document uploads in these formats and returns structured JSON with extracted fields based on configured templates or AI-powered field detection.

### How do webhooks work in Parsio?

Configure a webhook URL via POST `/mailboxes/{mailbox_id}/webhooks`, and Parsio will send a POST request with parsed JSON data to your endpoint immediately after a document is processed. Webhooks enable real-time automation without polling for results.

### Can I customize what fields are extracted from documents?

Yes. Parsio supports template-based parsing where you define extraction rules and field mappings in the mailbox settings. The API also supports AI-powered auto-detection of common fields like invoices, receipts, and forms without manual template configuration.

### What are the rate limits for the Parsio API?

Parsio's rate limits depend on your subscription plan. Standard plans support hundreds of documents per month with reasonable API request limits. Contact Parsio support for plan-specific rate limit details and enterprise volume pricing.

### Can I limit what my agent is allowed to do with the Parsio Document Parser API?

Yes. Because your Jentic One instance is self-hosted, you write the rules that decide which Parsio operations and credentials your agent may use. Since Parsio puts the mailbox id in the URL path, such as `/mailboxes/{mailbox_id}/documents`, a rule can pin the agent to a single mailbox so it can only upload documents and read parsed data there. You also choose the operations it can call, so actions like configuring webhooks via POST `/mailboxes/{mailbox_id}/webhooks` stay off-limits unless you grant them.