canonical: https://jentic.com/apis/perfectparser.com/perfectparser # PerfectParser Public API The PerfectParser Public API extracts structured data from documents using parsers you define: each parser has a name, a result mode of one object per file or per page, and a list of schema fields, which it can also detect automatically from a sample file and an optional prompt. You submit one or more files to a parser as a bulk extraction, follow its status from queued through processing to completed, failed, or partial, and read the results per extraction or per document, exporting them as JSON, CSV, or XLSX. Webhook subscriptions deliver document-completed and job-completed events to your server, and account endpoints report your profile and remaining credits, which are deducted by page count. ## For AI agents Define document parsers with schema fields or auto-detect them from a sample, submit files for bulk extraction, poll status, and fetch or export structured results as JSON, CSV, or XLSX. ## Scope Does not generate or sign documents, store files as a document library, or run accounting workflows on the extracted data. Use for defining parsers and extracting structured data from documents only. ## Capabilities - Create a parser with a name, result_mode of one_per_file or one_per_page, and schema fields for the data to extract - Auto-detect a parser's schema fields from a sample_file_id with an optional prompt, replacing or extending the existing schema - Submit one or more files to a parser_id as a bulk extraction and list extractions by parser_id, status, or since date - Read structured results for a whole extraction or for one document within it - Export a batch or a single document's results as json, csv, or xlsx - Subscribe a webhook to extraction.document_completed or extraction.job_completed events with an optional secret sent in X-Webhook-Secret - Check account details and remaining credits before submitting a large batch ## Use cases ### Agent document extraction through Jentic An agent handling incoming invoices or forms finds the PerfectParser extraction operations through Jentic, submits the files to an existing parser_id, polls the extraction status, and reads the structured results back into its workflow. Jentic injects the X-API-Key header at call time, so the agent works with extracted fields and never sees the pp_live_ key. Example prompt: POST `/v1/extractions` with parser_id for the invoice parser and the two uploaded PDF files, poll GET `/v1/extractions/{extraction_id}` until status is completed, then GET `/v1/extractions/{extraction_id}/results` ### Build a parser from a sample document Instead of defining every field by hand, create a parser with POST `/v1/parsers` and a name, then call POST `/v1/parsers/{id}/detect-fields` with a sample_file_id and an optional prompt such as 'extract PO number, supplier, and line items'. Set replace_existing_schema to choose whether detected fields replace or add to the current schema, and refine the result with PATCH `/v1/parsers/{id}.` Example prompt: POST `/v1/parsers` with name 'Purchase Order Parser' and result_mode 'one_per_file', then POST `/v1/parsers/{id}/detect-fields` with sample_file_id from a sample upload and prompt 'extract PO number, supplier, and line items' ### Bulk results to spreadsheets Finance and operations teams export extraction batches for review. GET `/v1/extractions/{extraction_id}/export` with format csv or xlsx returns the whole batch, and the per-document export returns a single file's results. GET `/v1/extractions` filtered by status such as failed or partial finds batches that need attention. Example prompt: List GET `/v1/extractions` with parser_id for invoices and since '2026-11-01T00:00:00Z', then call GET `/v1/extractions/{extraction_id}/export` with format 'xlsx' for each completed batch ### Push results with webhooks POST `/v1/webhooks` registers a callback URL for extraction.document_completed and extraction.job_completed events, with an optional secret that PerfectParser sends in the X-Webhook-Secret header. POST `/v1/webhooks/{id}/test` sends a test delivery, and PATCH can pause a subscription with is_active. Example prompt: POST `/v1/webhooks` with url 'https://example.com/hooks/parsed', events extraction.document_completed and extraction.job_completed, and a secret, then POST `/v1/webhooks/{id}/test` ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/v1/parsers` | Create a parser | | POST | `/v1/parsers/{id}/detect-fields` | Auto-detect schema fields | | POST | `/v1/extractions` | Submit documents for extraction | | GET | `/v1/extractions/{extraction_id}` | Get extraction status | | GET | `/v1/extractions/{extraction_id}/results` | Get extraction results | | GET | `/v1/extractions/{extraction_id}/export` | Export batch results | | POST | `/v1/webhooks` | Create a webhook subscription | ## Key resources - **Parsers** — Create, list, read, update, delete parsers and auto-detect their schema fields - **Extractions** — Submit files, list and track extraction batches, read results, and export them - **Documents** — Read and export results for a single document within an extraction - **Webhooks** — Create, update, delete, list, and test webhook subscriptions - **Account** — Account details and remaining credits ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 44 / 100 - **Maturity:** Foundational - **Dimensions:** - Foundational Compliance: 52 / 100 - Developer Experience & Jentic Compatibility: 68 / 100 - AI-Readiness & Agent Experience: 21 / 100 - Agent Usability: 94 / 100 - Security: 50 / 100 - AI Discoverability: 82 / 100 - **View full report:** https://jentic.com/apis/perfectparser.com/perfectparser/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring PerfectParser by hand means sending the X-API-Key header, uploading files as multipart form data, polling extraction status, and following cursor pagination yourself. Through Jentic you install once, import PerfectParser from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** PerfectParser puts the parser id and extraction id in the URL path (`/v1/parsers/{id}` and `/v1/extractions/{extraction_id}/...`), so a rule can pin your agent to one parser's configuration or one extraction's results. You choose the operations it may call, so destructive ones like deleting a parser or a webhook subscription are not included unless you add them. - **Credential handling:** Your PerfectParser 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 'extract data from documents' or 'export extraction results', and Jentic returns the matching PerfectParser operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Mindee OCR API** — Document OCR with pre-built and custom models - **NanoNets** — Trainable OCR models for document data capture - **Veryfi OCR API** — Receipt, invoice, and bill data extraction - **Dropbox API** — File storage and sharing ## FAQ ### What authentication does the PerfectParser Public API use? Per its OpenAPI spec, the PerfectParser Public API takes an API access key in the `X-API-Key` header, for example a key beginning `pp_live_`. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time, so it never enters the agent's context. ### Can PerfectParser work out which fields to extract by itself? Yes. POST `/v1/parsers/{id}/detect-fields` takes a required sample_file_id and an optional prompt, and proposes schema fields for the parser. replace_existing_schema controls whether the detected fields replace the current ones. You can still edit fields afterwards with PATCH `/v1/parsers/{id}.` ### How do I extract data from documents through Jentic? Search Jentic for 'extract data from documents', load the schema for POST `/v1/extractions`, and send the parser_id with your files as multipart form data. Poll GET `/v1/extractions/{extraction_id}` for status, then read the results endpoint. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### What are the rate limits for the PerfectParser Public API? The OpenAPI spec does not specify rate limits. It states that credits are deducted by total page count, and GET `/v1/credits` returns your remaining balance. Check https://perfectparser.com for current limits. ### Is there a PerfectParser MCP server? You don't need an MCP server to give your agent the PerfectParser Public API. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls it. Operations are discovered on demand, so no extra tool definitions sit in the agent's context. ### Can I limit what my agent is allowed to do with the PerfectParser Public API? Yes. For example, write a rule that allows only POST `/v1/extractions`, GET `/v1/extractions/{extraction_id}`, and GET `/v1/extractions/{extraction_id}/results`, so the agent can submit files and read results but cannot change or delete parsers or webhook subscriptions. Every call it makes is logged by your Jentic One instance.