API Reference

The PerfectParser REST API lets you integrate document extraction into any application or automation pipeline.

All API requests are served at:

https://api.perfectparser.com

Machine-readable spec: openapi.json

API Resources

The API is structured around the following core resources:

• Authentication: Secure request signing using API Keys.
• Account: Verify your key and check credit balance (GET /v1/me, GET /v1/credits).
• API Integration Guide: Connect PerfectParser to scripts and automation tools.
• Automation Integrations: Polling, webhooks, idempotency, and retry patterns for Zapier, Make, n8n, and custom pipelines.
• Parsers: Managing extraction templates, schema designs, and sample files.
• Extractions: Submitting documents, checking status, retrieving results, and exporting — including per-document endpoints nested under each extraction job.
• Webhooks: Configuring outbound event triggers to receive results in real-time.

Which endpoint do I call?

Response Format

Successful responses wrap resources in a named envelope:

{
  "extraction": { "extraction_id": "ext_abc", "status": "processing" }
}

Common envelopes: { parser }, { extraction }, { document }, { user }, { credits }, { webhooks }, { webhook }.

List endpoints return { items: [...], next_cursor: "..." } or similar pagination fields.

Errors return a 4xx or 5xx status with a structured payload:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API key is required. Pass your key via the X-API-Key header.",
    "status": 401
  }
}

Every response includes rate-limit headers — see Authentication.

Error Codes

PerfectParser returns standard HTTP status codes combined with machine-readable error strings in the response body.