`POST /v1/extractions`

Submit one or more document files (PDFs, images) to a specific Parser for asynchronous structured data extraction.

This endpoint automatically counts pages server-side and bills your credit balance (1 page = 1 credit). If your balance is insufficient, the request is rejected with a 402 error.

The parser must have a configured schema. Submitting to an unconfigured parser returns a 400 PARSER_NOT_CONFIGURED error.

Headers

Header	Required	Description
`X-API-Key`	✅ Yes	Your PerfectParser API key.
`Content-Type`	✅ Yes	`multipart/form-data`
`Idempotency-Key`	Optional	Unique string (max 24h). Retries with the same key return the original job without double-charging. Response includes `Idempotent-Replayed: true` on replay.

This endpoint has a tighter rate limit of 20 requests/minute per API key (vs 150/min global).

Body Parameters (Multipart Form)

Parameter	Type	Required	Description
`parser_id`	`string`	✅	The ID of the parser to process these files.
`files`	`file(s)`	✅	One or more document files (PDF, PNG, JPG, JPEG, WebP, etc.). Up to 50 files.

curl -X POST https://api.perfectparser.com/v1/extractions \
  -H "X-API-Key: pp_live_your_secret_key" \
  -H "Idempotency-Key: batch-invoice-june-2026" \
  -F "parser_id=prs_999" \
  -F "files=@invoice-1.pdf" \
  -F "files=@invoice-2.pdf"

Response 202 Accepted

{
  "extraction": {
    "extraction_id": "ext_123",
    "parser_id": "prs_999",
    "status": "queued",
    "file_count": 2,
    "page_count": 7,
    "credits_used": 7,
    "credits_remaining": 43,
    "documents": [
      {
        "document_id": "doc_1",
        "filename": "invoice-1.pdf",
        "page_count": 3,
        "credits_used": 3,
        "status": "queued"
      },
      {
        "document_id": "doc_2",
        "filename": "invoice-2.pdf",
        "page_count": 4,
        "credits_used": 4,
        "status": "queued"
      }
    ]
  }
}

Save extraction_id and each document_id — use them for status polling and nested document endpoints.

Common Error Responses

HTTP Status	Error Code	Description
`400`	`INVALID_PAYLOAD`	Missing required multipart parameter (`parser_id` or `files`).
`400`	`PARSER_NOT_CONFIGURED`	Parser exists but has no schema configured.
`400`	`UNSUPPORTED_FILE_TYPE`	One or more uploaded files are not supported.
`400`	`PAGE_COUNT_FAILED`	File analysis failed.
`401`	`UNAUTHORIZED`	Invalid or missing API key.
`402`	`INSUFFICIENT_CREDITS`	Account credit balance too low.
`404`	`PARSER_NOT_FOUND`	Parser not found or belongs to another account.
`429`	`RATE_LIMITED`	More than 20 extraction submissions per minute.

Submit Extraction

`POST /v1/extractions`

Common Error Responses

On this page