👨‍💻 Parse PDF and Files Using API

In this article, we’ll see how to upload PDF and other files using the Parsio API.

Use these endpoints when your source document is an actual file. The request contains the file itself as binary data, which Parsio then processes and parses. If your document already exists as plain text or HTML, use the text/HTML API instead.

Which endpoint should I use?

For most API integrations, we recommend /upload-sync because it returns parsed data directly in the same HTTP response whenever parsing finishes within the timeout.

Use /upload if you prefer webhooks, want fire-and-forget ingestion, need ZIP upload support, or do not want the request to wait for parsing.

Recommended: POST https://api.parsio.io/mailboxes/<mailbox_id>/upload-sync
Asynchronous alternative: POST https://api.parsio.io/mailboxes/<mailbox_id>/upload

Parser Compatibility

File upload works with all Parsio parser types, but supported file formats depend on the mailbox type.

Template-based parser: supports text-based business documents such as TXT, HTML, XML, JSON, PDF, DOCX, CSV, Excel, RTF, EML, and ZIP
GPT-powered parser: supports PDF, EML, HTML, TXT, DOCX, XML, JSON, and ZIP
AI-powered parser: supports PDF, images, and ZIP
OCR converter: supports PDF and images, with exact image formats depending on the OCR engine

Authentication

To access the API, you will need the API key that you will find in your account:

This API key should be included in the X-API-Key HTTP header.

Unauthenticated responses return HTTP 401 Unauthorized.

Example request using cURL:

curl -X GET https://api.parsio.io/mailboxes/ -H "X-API-Key: <YOUR_API_KEY>"

Parameters

file: Binary file object
meta (optional): Custom payload included in the parsed JSON as __meta__

In multipart form-data requests, meta can be provided either as a JSON object or as a JSON-encoded string.

Your Mailbox ID can be found in the browser location bar:

Limits and Notes

Synchronous upload: `/upload-sync`

One file per request
ZIP files are not supported
Max. file size: 20MB

If parsing finishes within the timeout, Parsio returns the parsed result in the same response. If parsing takes longer, Parsio returns parsing_in_progress: true and continues parsing in the background.

Asynchronous upload: `/upload`

One file per request
ZIP files supported
Max. file size: 50MB

Use /upload when you want the fastest possible response or when you plan to consume the parsed result later through webhooks or by calling GET /docs/<doc_id>.

How Responses Work

Synchronous response

If parsing finishes within the timeout, Parsio returns a JSON object like this:

{
  "doc_id": "DOC_ID",
  "parsing_in_progress": false,
  "status": "parsed",
  "name": "receipt.pdf",
  "content_type": "application/pdf",
  "created_at": "2026-04-02T12:00:00.000Z",
  "processed_at": "2026-04-02T12:00:06.000Z",
  "json": {
    "field1": "value1"
  }
}

If parsing does not finish within the timeout, Parsio returns:

{
  "doc_id": "DOC_ID",
  "parsing_in_progress": true,
  "status": "parsing",
  "name": null,
  "content_type": null,
  "created_at": null,
  "processed_at": null,
  "json": null
}

In that case, parsing continues in the background. You can then retrieve the result later using GET /docs/<doc_id> or receive it via webhook.

Asynchronous response

The asynchronous upload endpoint returns the created document ID and starts parsing in the background.

Code Samples

cURL — recommended synchronous request:

curl -X POST https://api.parsio.io/mailboxes/<YOUR_MAILBOX_ID>/upload-sync -H "X-API-Key: <YOUR_API_KEY>" -F 'file=@./receipt.pdf'

cURL — synchronous request with metadata:

curl -X POST https://api.parsio.io/mailboxes/<YOUR_MAILBOX_ID>/upload-sync -H "X-API-Key: <YOUR_API_KEY>" -F 'file=@./receipt.pdf' -F 'meta={"external_id":"12345","source":"api"}'

cURL — asynchronous request:

curl -X POST https://api.parsio.io/mailboxes/<YOUR_MAILBOX_ID>/upload -F 'file=@./receipt.pdf' -H "X-API-Key: <YOUR_API_KEY>"

cURL — synchronous integration upload:

curl -X POST https://api.parsio.io/mailboxes/<YOUR_MAILBOX_ID>/upload-sync/zapier -H "X-API-Key: <YOUR_API_KEY>" -F 'file=@./receipt.pdf'