Parse Document API

Q: Should I use TemplateId or TemplateName?

Use TemplateId in production automation. It is a stable GUID generated by the dashboard when you click Save Changes on a template and never changes for the life of the template. TemplateName works as a lookup alternative but breaks if you rename the template in the dashboard. Pass TemplateId in every production call.

Q: What is ParseId and where does it come from?

ParseId is a client-generated GUID you create per call (uuid.uuid4 in Python, Guid.NewGuid in C#, UUID.randomUUID in Java). Pass it in the request body for logging and audit trail correlation. The API does not validate ParseId against any registry, so any valid GUID works.

What this endpoint does

PDF4me Parse Document runs your saved parse template against a PDF and returns the extracted fields as JSON in a single REST call. Send the PDF as Base64, the TemplateId from the dashboard, and a client-generated ParseId, and receive a structured response keyed by the names you defined in the template. The template carries the extraction logic (Regex Expression for stable patterns, JavaScript Expression for conditional rules), so this same call extracts invoices, contracts, receipts, and any custom document layout you have configured.

Authenticating Your API Request

Every PDF4me REST call must include your API key in the Authorization header. Create or select a key from the developer dashboard and keep it server-side. Never expose it in browser code.

Get your API Key

Important Facts You Should Not Miss

Minimum payload is three fields, not five

Only docContent, docName, and async are required. TemplateId, TemplateName, and ParseId are optional and only needed when you want the response keyed by your custom capture fields. Without them the API still returns useful default fields such as documentType and pageCount.

Response is JSON, not binary

Parse Document returns application/json with one field per capture key in your template plus default fields. This is different from Protect, Compress, and Convert endpoints which return raw binary PDFs. Parse Document always returns JSON because it returns structured data, not a file.

Use TemplateId, not TemplateName, in production

TemplateId is a stable GUID assigned by the dashboard at Save Changes. It never changes for the life of the template. TemplateName works as a lookup alternative but breaks if you rename the template. Always copy TemplateId from the template detail panel and pin it in your code.

REST API endpoint

Method: POST
URL: https://api.pdf4me.com/api/v2/ParseDocument

Send Content-Type: application/json and an Authorization header with your API key. Set async to false for a synchronous response (HTTP 200 with parsed JSON), or true to receive HTTP 202 plus a Location header that you poll until it returns 200 with the parsed JSON.

Postman request setup

Setting	Value
Method	POST
URL	https://api.pdf4me.com/api/v2/ParseDocument
Headers	Content-Type: application/json
Authorization	Basic Auth with your API key, or header Authorization: Basic YOUR_API_KEY
Body	raw JSON with docContent, docName, async (and optional TemplateId, TemplateName, ParseId)
Response (sync)	When async is false: HTTP 200 with parsed JSON containing one field per template key plus default fields such as documentType and pageCount.
Response (async)	When async is true: HTTP 202 with a Location header. GET that URL until you receive 200 with the parsed JSON. Useful for large PDFs or batch processing.

Parameters

Always required: docContent, docName, async. Conditional (template-based extraction): TemplateId (recommended) or TemplateName plus ParseId. Without these the API still returns useful default fields (documentType, pageCount) but no custom-keyed values.

Parameter	Required	Type	What it does	Example
`docContent`	Yes	Base64 String	The source PDF file encoded as Base64 (no data: prefix). Read the file as bytes and run it through your language's Base64 encoder.	`JVBERi0xLjQK...`
`docName`	Yes	String	Filename of the source PDF including .pdf extension. Used for tracking and error messages.	`invoice.pdf`
`async`	Yes	Boolean	Processing mode. false returns parsed JSON immediately with HTTP 200. true returns HTTP 202 plus a Location header that you poll until it returns 200 with the parsed JSON. Use true for large PDFs or batch processing.	`true`
`TemplateId`	Conditional	String (GUID)	GUID of the saved parse template. Recommended over TemplateName for stable production automation. Get it from the template detail panel after Save Changes in the dashboard.	`12345678-1234-1234-1234-123456789abc`
`TemplateName`	Conditional	String	Template name as typed in the dashboard. Lookup alternative to TemplateId. Renaming the template breaks calls that reference it by name, so prefer TemplateId in production.	`invoice_template`
`ParseId`	Conditional	String (GUID)	Client-generated GUID per call. Used to correlate the request with the parse output for logging and audit trails. Generate with uuid.uuid4 (Python), Guid.NewGuid (C#), UUID.randomUUID (Java).	`87654321-4321-4321-4321-cba987654321`

Request examples

Example A: Minimum payload (no template)

The smallest call the API accepts. Returns default fields (documentType, pageCount) but no custom-keyed values because no template is referenced.

{
 "docContent": "JVBERi0xLjQK...",
 "docName": "invoice.pdf",
 "async": true
}

Example B: Template-based extraction (production pattern)

The recommended production payload. Returns one field per capture key defined in your template plus default fields.

{
 "docContent": "JVBERi0xLjQK...",
 "docName": "invoice.pdf",
 "TemplateId": "12345678-1234-1234-1234-123456789abc",
 "ParseId": "87654321-4321-4321-4321-cba987654321",
 "async": true
}

Example C: Template lookup by name

Lookup alternative when you do not have a TemplateId handy. Avoid in production because renaming the template breaks this call.

{
 "docContent": "JVBERi0xLjQK...",
 "docName": "invoice.pdf",
 "TemplateName": "invoice_template",
 "ParseId": "87654321-4321-4321-4321-cba987654321",
 "async": true
}

Successful response (sync, `async: false`)

HTTP 200 with the parsed JSON. Each capture key from your template becomes a field. Default fields (documentType, pageCount) are always returned.

{
 "parsedData": {
 "invoiceNumber": "INV-2024-001",
 "invoiceDate": "15/01/2024",
 "totalAmount": "$1,250.50",
 "customerName": "Acme Corporation"
 },
 "documentType": "invoice",
 "pageCount": 1
}

Successful response (async, `async: true`)

HTTP 202 with a Location header. Poll that URL with GET (same Authorization header) until you receive HTTP 200 with the parsed JSON.

HTTP/1.1 202 Accepted
Location: https://api.pdf4me.com/api/v2/ParseDocumentStatus/<job-id>

curl example

curl -X POST https://api.pdf4me.com/api/v2/ParseDocument \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic YOUR_API_KEY" \
 -d '{
 "docContent": "JVBERi0xLjQK...",
 "docName": "invoice.pdf",
 "TemplateId": "12345678-1234-1234-1234-123456789abc",
 "ParseId": "87654321-4321-4321-4321-cba987654321",
 "async": true
 }'

Template setup

The parse template carries all the extraction logic. Configure it once in the dashboard, then call by TemplateId from anywhere.

Regex ExpressionStable patterns

Invoice numbers (INV-\d{6,10}), dates (\d{2}/\d{2}/\d{4}), amounts ($?\d{1,3}(?:,\d{3})*(?:.\d{2})?), tax IDs, postal codes. Use for around 80% of production keys.

JavaScript ExpressionConditional logic and classifiers

Multi-marker classification, fallback rules, document type detection. The extracted text is passed as the variable text; your function returns a string. See Prepare Parse Info for Document for two working classifier samples (functionFormatTextDate1 and functionGetInvoiceOrder).

Full template setup guide Open Parse Document Dashboard

Code samples

Pre-built samples that load a PDF, encode it as Base64, POST to /api/v2/ParseDocument, and handle the sync / async response.

Integration examples

Common REST integration patternsTypical ways developers call Parse Document.

Invoice inbox to accounting database

A watcher picks up new vendor PDFs from an email inbox or cloud folder.
Your service reads each PDF as bytes and encodes it as Base64.
POST to /api/v2/ParseDocument with the invoice TemplateId and a fresh ParseId.
Map the returned invoiceNumber, totalAmount, and invoiceDate straight into a database INSERT.

Mixed-document classifier plus extractor

A JavaScript Expression key in the template returns the document type (invoice, order, terms).
POST returns the type along with the regex-extracted fields in one JSON response.
Your code branches on the type field and routes the structured data to the right downstream system.

Batch async processing of large PDFs

For files over a few MB, POST with async: true.
Read the Location header from the 202 response.
Poll the URL with GET every 10 seconds (the Python sample uses 15 max retries).
When the response status is 200, parse the JSON body and continue downstream processing.

Frequently Asked Questions

What is the minimum payload required by the Parse Document REST API?+

Three fields: docContent (the PDF as Base64), docName (filename with .pdf), and async (boolean for sync vs polling). TemplateId, TemplateName, and ParseId are optional. Without a template the API returns default information (documentType, pageCount) but no custom-keyed values.

Should I use TemplateId or TemplateName?+

Use TemplateId in production. It is a stable GUID generated by the dashboard at Save Changes and never changes for the life of the template. TemplateName works as a lookup alternative but breaks if you rename the template. Always pin TemplateId in your code.

What is ParseId and where does it come from?+

ParseId is a client-generated GUID you create per call: uuid.uuid4 in Python, Guid.NewGuid in C#, UUID.randomUUID in Java. Pass it in the request body for logging and audit trail correlation. The API does not validate it against a registry, so any valid GUID works.

Is the response JSON or binary?+

JSON. The response body is application/json containing one field per capture key in your template plus default fields such as documentType and pageCount. This is different from Protect, Compress, and Convert endpoints which return raw binary PDFs.

How does async work for large or batch PDFs?+

Set async to true. The API responds with 202 Accepted plus a Location header containing a poll URL. GET that URL with the same Authorization header. While the document is still processing the poll URL returns 202; when finished it returns 200 with the parsed JSON. Use async true for files over a few MB or when processing in batches.

How is this different from regex parsing in Python with pdfplumber?+

Python libraries like pdfplumber, PyMuPDF, and pdfminer give you raw text extraction primitives and you write the matching logic in your application code. PDF4me Parse Document uses templates you configure once in a hosted dashboard, then calls run that template from any language or platform. The matching logic lives in the template, not your code, which keeps it consistent across systems.

Where do I learn the Regex Expression and JavaScript Expression syntax?+

See the full Prepare Parse Info for Document setup guide. It covers Regex patterns for invoice numbers, dates, and amounts, and includes two working JavaScript Expression classifier samples (functionFormatTextDate1 for Terms and Conditions vs Order classification, functionGetInvoiceOrder for invoice vs order detection).

Can I run the same template from Make, Zapier, Power Automate, or n8n?+

Yes. The TemplateId is the same across all platforms. The Make, Zapier, Power Automate, and n8n PDF4me modules call this same endpoint under the hood. Build and test the template once in the dashboard, then reference its TemplateId from any platform.

Prepare Parse Info for Document

Template setup walkthrough with Regex examples and two working JavaScript Expression classifier samples.

Set Up Classify Document

Companion guide for category-only outputs without field extraction. Useful as a pre-router before Parse Document.

Extract Text by Expression

Lower-level endpoint that runs a single regex against a PDF without a saved template. Useful for ad-hoc extraction.