Fill a PDF Form

Q: How do I know the exact AcroForm field names?

Open the template in Adobe Acrobat (Prepare Form), in any PDF editor with field inspection, or call the PDF4me Extract Form Data endpoint first. The keys in your dataArray JSON must match those names exactly, including case.

Q: When should I use Variant B (PDF URL) over Variant A (Base64)?

Use Variant B (publicly reachable HTTPS URL) when the template is already hosted somewhere the PDF4me service can fetch. It avoids the Base64 size bloat (~33%) and is the simplest path for templates pinned in S3, CDN, or your own static asset host. Use Variant A when the template is private or only available as a local file.

Q: How does the async flow work?

Send IsAsync true. If the request returns 200, the binary PDF is in the body. If it returns 202, read the Location response header for a poll URL. GET that URL with the same Authorization header. Continue polling (commonly 10s intervals up to 15 retries) until it returns 200 with the PDF.

What this endpoint does

PDF4me Fill a PDF Form populates AcroForm fields in a PDF template with values from a JSON object in a single REST call. Send the template as Base64 or a public URL, send the field values as a stringified dataArray, and receive the filled PDF as binary bytes (200) or via a Location-header poll URL (202). Toggle KeepPdfEditable to deliver a re-editable form or a flattened static record.

Authenticating Your API Request

Every PDF4me REST call must include your API key in the Authorization header as Basic auth. Get or rotate your key from the developer dashboard.

Get your API Key

Endpoint

POST/api/v2/FillPdfForm

Postman URLhttps://api.pdf4me.com/api/v2/FillPdfForm

Important Facts You Should Not Miss

dataArray is a STRING, not an object

The API expects a stringified JSON. Always wrap your form payload in JSON.stringify({...}) before posting. Sending a nested object returns a deserialization error.

Keys must match AcroForm field names exactly

Field names are case-sensitive. Inspect the template with Adobe Acrobat Prepare Form or call the Extract Form Data endpoint first to get a clean list of every fillable field.

Async returns 202 + Location header

With IsAsync: true the API may respond 202 and a Location header. GET that URL (same Authorization) until it returns 200 with the PDF binary. Standard PDF4me async pattern (pdf4meAsyncRequest).

HTTP setup

Method: POST
URL: https://api.pdf4me.com/api/v2/FillPdfForm
Content-Type: application/json
Authorization: Basic <your PDF4me API key>

Send IsAsync: true in the body. 200 returns the filled PDF as binary bytes. 202 returns a Location header with a poll URL; GET that URL with the same Authorization header until it returns 200 with the PDF binary (same convention as pdf4meAsyncRequest).

Variant matrix (Postman-relevant)

Three input variants cover every Postman / curl / SDK call. Pick the variant that matches where your PDF template and form data live.

Variant	PDF template (`templateDocContent`)	Form fields	Required API fields
A	Base64 PDF	JSON object → stringify → dataArray	All rows in the JSON-form table below.
B	Public PDF URL	JSON object → stringify → dataArray	Same as A; templateDocContent is the URL string.
C	Base64 PDF	Base64-encoded JSON file → decode → stringify into dataArray	Same as A; build dataArray from the decoded JSON.

API body fields

Always sent

Field	Required	Type	Default / notes
`templateDocName`	Yes*	string	Filename of the template, e.g. template.pdf. Derived from the source URL filename or defaulted to template.pdf. Used for downstream output naming.
`templateDocContent`	Yes	string	Base64-encoded PDF (no data: prefix) OR a publicly reachable https URL to the PDF.
`KeepPdfEditable`	No	boolean	Default false. Set true to keep AcroForm fields editable in the output PDF; false flattens the form into static text.
`IsAsync`	Yes	boolean	Default true. Toggles the 200 / 202 + Location async pattern.

*templateDocName must always be set in the request; pick a sensible filename so output filenames are clean downstream.

When form input is JSON

Field	Required	Type	Notes
`dataArray`	Yes	string	JSON.stringify({ ... }). Keys = AcroForm field names; values = strings to fill.
`inputDataType`	Yes	string	Always "json" for this path.
`outputType`	Yes	string	Always "pdf".

Form data rules (JSON path)

Rule	Detail
Shape	Single object: {"fieldName": "value", ...}.
Not allowed	Empty array, or an array of multiple objects.
Base64 form input	Decode the UTF-8 JSON file, then JSON.stringify into dataArray. In Postman: put the decoded-then-stringified result directly into dataArray.
Data URL	Strip the data:...;base64, prefix if present (applies to the PDF Base64 in templateDocContent).

Sample payloads

Variant A. PDF Base64 + form JSON

{
 "templateDocName": "application-form.pdf",
 "templateDocContent": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZw...",
 "dataArray": "{\"firstname\": \"John\", \"lastname\": \"Doe\", \"email\": \"[email protected]\"}",
 "inputDataType": "json",
 "outputType": "pdf",
 "KeepPdfEditable": false,
 "IsAsync": true
}

dataArray must be a string, not a nested JSON object:
"dataArray": "{"firstname":"John","lastname":"Doe"}"

Variant B. PDF URL + form JSON

{
 "templateDocName": "application-form.pdf",
 "templateDocContent": "https://example.com/forms/application-form.pdf",
 "dataArray": "{\"firstname\": \"John\", \"lastname\": \"Doe\", \"email\": \"[email protected]\"}",
 "inputDataType": "json",
 "outputType": "pdf",
 "KeepPdfEditable": false,
 "IsAsync": true
}

Variant C. PDF Base64 + form from base64 JSON

Placeholder in repo: eyJmaXJzdG5hbWUiOiJKb2huIn0= → {"firstname":"John"}.

Equivalent API body after decoding the form JSON:

{
 "templateDocName": "application-form.pdf",
 "templateDocContent": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZw...",
 "dataArray": "{\"firstname\": \"John\"}",
 "inputDataType": "json",
 "outputType": "pdf",
 "KeepPdfEditable": false,
 "IsAsync": true
}

Optional. keep form editable

{
 "templateDocName": "application-form.pdf",
 "templateDocContent": "https://example.com/forms/application-form.pdf",
 "dataArray": "{\"firstname\": \"John\", \"lastname\": \"Doe\"}",
 "inputDataType": "json",
 "outputType": "pdf",
 "KeepPdfEditable": true,
 "IsAsync": true
}

Postman collection tips

Headers

Content-Type: application/json + Authorization: Basic <apiKey>.

Body

raw JSON. Copy one of the variant payloads above.

Response

Save as .pdf when status is 200 and the body is binary. If 202, GET the Location URL with the same Authorization until 200.

Field names

Must exactly match AcroForm names in the template. Use the Extract Form Data endpoint or a PDF editor if you are unsure.

curl example

curl -X POST https://api.pdf4me.com/api/v2/FillPdfForm \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic YOUR_API_KEY" \
 -d '{
 "templateDocName": "application-form.pdf",
 "templateDocContent": "https://example.com/forms/application-form.pdf",
 "dataArray": "{\"firstname\":\"John\",\"lastname\":\"Doe\"}",
 "inputDataType": "json",
 "outputType": "pdf",
 "KeepPdfEditable": false,
 "IsAsync": true
 }' \
 --output filled-form.pdf

Quick reference: required vs optional (Postman)

Field	A (PDF b64)	B (PDF URL)	C (form b64 → JSON)
`templateDocName`	Required	Required	Required
`templateDocContent`	Required (b64)	Required (URL)	Required (b64)
`dataArray`	Required	Required	Required (from decoded JSON)
`inputDataType`	Required (json)	Required (json)	Required (json)
`outputType`	Required (pdf)	Required (pdf)	Required (pdf)
`IsAsync`	Required (true)	Required (true)	Required (true)
`KeepPdfEditable`	Optional	Optional	Optional

Code samples

FAQ

Why must dataArray be a stringified JSON, not a nested object?+

The API contract defines dataArray as a string field. The engine parses the string server-side. Sending a nested object returns a deserialization error. Always wrap your form values with JSON.stringify before posting.

What happens when KeepPdfEditable is true?+

The output PDF retains its AcroForm field definitions so the recipient can re-edit values in any PDF viewer. KeepPdfEditable false (the default) flattens the form into static text, useful for delivering a locked record of what was submitted.

How do I know the exact AcroForm field names?+

Open the template in Adobe Acrobat (Prepare Form), use any PDF editor with field inspection, or call the PDF4me Extract Form Data endpoint first. Keys in your dataArray JSON must match those names exactly, including case.

When should I use Variant B (PDF URL) over Variant A (Base64)?+

Use Variant B when the template is already hosted at a publicly reachable HTTPS URL. It avoids the Base64 size bloat (~33%) and is the simplest path for templates pinned in S3, CDN, or your own static asset host. Use Variant A when the template is private or local.

How does the async flow work?+

Send IsAsync true. If the API returns 200, the PDF binary is in the body. If it returns 202, read the Location response header for a poll URL. GET that URL with the same Authorization header. Continue polling (commonly 10s intervals up to 15 retries) until it returns 200 with the PDF.

Can I send an array of multiple form-data objects?+

No. The REST contract requires a single object inside dataArray (after JSON.stringify). To fill many forms, call the endpoint once per form.

My PDF Base64 has a data: prefix. Do I strip it?+

Yes. The API expects raw Base64 in templateDocContent. Strip any data:application/pdf;base64, prefix before posting.

How do I get back something other than PDF?+

You cannot. outputType is fixed to pdf for this endpoint. To rasterize the filled PDF into PNG / JPEG, chain a downstream PDF4me Convert PDF to Image call.

Extract Form Data

Companion endpoint. Pull the field names + current values out of any AcroForm PDF before designing your dataArray payload.

Sign a PDF

Common chained step: fill the form, then digitally sign it before delivery.

Protect Document

Apply password protection and permissions after filling. Useful when delivering filled forms via email.