Synchronous Processing

Use the synchronous API when you want the extracted JSON immediately in the HTTP response.

Endpoint

POST /documents/parse

Authentication

x-api-key: your_api_key_here

Request Body

Send multipart/form-data.

Field	Type	Description	Required
files	File or File[]	Document(s) to process	Yes, unless fileUrl is provided
templateId	UUID	Existing template ID	Yes
language	string	Optional OCR language hint	No
fileUrl	URL	Public file URL to fetch instead of uploading	No

Supported Formats

• PDF
• PNG
• JPG / JPEG
• WEBP
• TIFF
• BMP
• ZIP

Processing Modes

The sync endpoint automatically handles:

1. Single document
2. Multiple uploaded documents
3. ZIP archives

Plan Rules

• Free users can process one document at a time
• Multi-document sync processing requires a paid plan
• The endpoint accepts up to 10 uploaded files in one request

Example Requests

Single File

curl -X POST https://api.parselyze.com/documents/parse \
  -H "x-api-key: YOUR_API_KEY" \
  -F "files=@invoice.pdf" \
  -F "templateId=YOUR_TEMPLATE_ID"

Multiple Files

curl -X POST https://api.parselyze.com/documents/parse \
  -H "x-api-key: YOUR_API_KEY" \
  -F "files=@document-1.pdf" \
  -F "files=@document-2.jpg" \
  -F "templateId=YOUR_TEMPLATE_ID"

ZIP Archive

curl -X POST https://api.parselyze.com/documents/parse \
  -H "x-api-key: YOUR_API_KEY" \
  -F "files=@documents.zip" \
  -F "templateId=YOUR_TEMPLATE_ID"

Remote File URL

curl -X POST https://api.parselyze.com/documents/parse \
  -H "x-api-key: YOUR_API_KEY" \
  -F "templateId=YOUR_TEMPLATE_ID" \
  -F "fileUrl=https://example.com/invoice.pdf"

JavaScript/Node.js example

import { Parselyze } from "parselyze";

const parselyze = new Parselyze("plz_xxxxxxxx...xxxxxx");

(async function () {
  console.log("Start parsing document...");

  const result = await parselyze.documents.parse({
    files: ["./invoice.pdf"],
    templateId: "<YOUR_TEMPLATE_ID>",
  });

  console.log("Parsing complete:", result);
})();

Response Shape

Single Document

{
  "result": {
    "invoice": {
      "number": "INV-2025-001",
      "date": "2025-05-26",
      "total": 1250.75
    }
  },
  "pageCount": 1,
  "pageUsed": 1,
  "pageRemaining": 999
}

Multiple Documents

{
  "results": [
    {
      "filename": "document-1.pdf",
      "result": {
        "invoice": {
          "number": "INV-2025-001"
        }
      }
    },
    {
      "filename": "document-2.jpg",
      "result": {
        "invoice": {
          "number": "INV-2025-002"
        }
      }
    }
  ],
  "pageCount": 3,
  "pageUsed": 3,
  "pageRemaining": 997
}

Quota Behavior

• pageCount = total pages in the uploaded document(s)
• pageUsed = pages successfully billed for this request
• pageRemaining = remaining quota after the request

If parsing fails for a given document, pageUsed is 0 for that failed document path.

Current Limitations

• Scanned PDFs over 30 pages are not supported yet
• Templates must already exist in the dashboard

Error Shape

Many extraction problems are returned inside a successful 200 response:

{
  "result": {
    "error": "No text could be extracted from the document."
  },
  "pageCount": 1,
  "pageUsed": 0,
  "pageRemaining": 999
}

For multi-document requests, each file can succeed or fail independently inside results[].

See Error Handling for transport-level errors such as auth, rate limits, and malformed uploads.