Polling, webhooks, idempotency, and retry patterns for Zapier, Make, n8n, and custom pipelines.

This guide covers integration patterns for automation tools and custom backends. For endpoint details, see the API Reference.

Pre-flight checks

Before submitting extractions in production:

GET /v1/me — confirm your API key works and check user.credits_available.
GET /v1/credits — inspect active purchase breakdown if you need detailed balance info.

Polling workflow

For simple scripts or when webhooks are not available:

POST /v1/extractions  →  poll GET /v1/extractions/:id  →  GET /v1/extractions/:id/results

For automation platforms that poll on a schedule, use the list endpoint with filters:

GET /v1/extractions?since=2026-06-20T10:00:00Z&status=completed&limit=50

Parameter	Purpose
`since`	Only jobs updated after this ISO 8601 timestamp
`status`	`queued`, `pending`, `processing`, `completed`, `failed`, `partial`
`parser_id`	Limit to one parser

Webhook workflow

Recommended for Zapier, Make, n8n, and production pipelines:

Create webhook — POST /v1/webhooks with your callback URL and events.
Store signing_secret — returned once in the create response.
Test delivery — POST /v1/webhooks/:id/test before going live.
Handle events — respond with 2xx immediately; process payload asynchronously.

Subscribe to:

Event	When to use
`extraction.document_completed`	Process each file as it finishes (best for large batches)
`extraction.job_completed`	Wait for the entire batch to finish

Retry a failed webhook delivery

Webhook payloads include extraction_id and document_id. If your handler missed a delivery or timed out, fetch the result directly:

GET /v1/extractions/{extraction_id}/documents/{document_id}

Example (Node.js):

async function retryDocument(extractionId: string, documentId: string) {
  const res = await fetch(
    `https://api.perfectparser.com/v1/extractions/${extractionId}/documents/${documentId}`,
    { headers: { "X-API-Key": process.env.PP_API_KEY! } }
  );
  const { document } = await res.json();
  return document.extracted_data;
}

Idempotency for extractions

Network retries can accidentally submit the same batch twice. Pass a unique Idempotency-Key header on POST /v1/extractions:

curl -X POST https://api.perfectparser.com/v1/extractions \
  -H "X-API-Key: pp_live_..." \
  -H "Idempotency-Key: invoice-batch-2026-06-20-001" \
  -F "parser_id=prs_999" \
  -F "files=@invoice.pdf"

If the same key is reused within 24 hours, the API returns the original job with Idempotent-Replayed: true — no double charge.

Credit safety

Check	Endpoint
Quick balance	`GET /v1/me` → `user.credits_available`
Detailed balance	`GET /v1/credits` → `credits.available`
Pre-submit estimate	Page count is returned in the `202` response (`extraction.page_count`, `extraction.credits_used`)

If credits are insufficient, POST /v1/extractions returns 402 INSUFFICIENT_CREDITS before any processing starts.

Rate limits

Scope	Limit
All endpoints	150 requests/minute per API key
`POST /v1/extractions`	20 requests/minute

Respect X-RateLimit-Reset and use exponential back-off on 429 responses.

Webhooks — verification, payloads, retries
Submit Extraction — idempotency and multipart upload
Get Document — nested single-document fetch

Automation Integrations