Linearize PDF

PDF4me Linearize PDF is a REST endpoint that restructures a PDF for fast web view. POST the file as Base64 to /api/v2/LinearizePdf with an optimizeProfile, and the API reorders its internal objects so the first page renders while the rest is still downloading, then returns the linearized PDF as raw bytes. Nine profiles cover web, print, and compression.

What this endpoint does

Takes a PDF and returns the same document reorganized for progressive loading: directory information and page 1 resources move to the front of the file, so a browser or embedded viewer shows the first page almost immediately instead of waiting for the whole download. The pages themselves are untouched. Ideal for document portals, CDNs, and any PDF served over HTTP.

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/LinearizePdf

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

Important Facts You Should Not Miss

The flag is async, not IsAsync

The official samples send the asynchronous switch as lowercase async, a JSON boolean. A wrongly cased key is silently ignored and your large file processes synchronously.

A 200 response is the PDF itself

The body is raw binary: write it straight to a .pdf file. The official samples also handle a JSON-wrapped Base64 fallback defensively, but the primary contract is bytes.

Same pages, different byte order

Linearization never edits content. It reorders internal objects so page 1 and the document catalog sit at the front of the file, which is what lets viewers render before the download finishes.

HTTP setup

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

A 200 response body is the linearized PDF as raw bytes: save it directly. A 202 response means asynchronous processing: poll the Location URL with GET about every 10 seconds (the official samples use 10s intervals, up to 10 retries) until 200.

Which optimizeProfile should I choose?

Nine profiles are accepted. They fall into three families with different goals.

Profile family vs goal	Profiles	What they optimize for
Web	`web`, `WebMax`	Progressive display and fast first-page rendering in browsers; WebMax is the most aggressive web optimization
Print	`Print`, `PrintMax`, `PrintGray`	Print-oriented output; PrintGray also converts toward grayscale printing
Compression	`Compress`, `CompressMax`	Smallest file size; CompressMax trades more processing for more reduction
General	`Default`, `Max`	The engine defaults, and the maximum overall optimization level

For PDFs served on websites, start with web and step up to WebMax only if first-page latency still matters after testing.

API body fields

Parameter	Required	Type	What it does	Example
`docContent`	Required	string	Base64-encoded bytes of the source PDF.	`JVBERi0xLjcK...`
`docName`	Required	string	Source PDF filename with its .pdf extension.	`document.pdf`
`optimizeProfile`	Required	string	Optimization profile. Allowed values: web, Max, Print, Default, WebMax, PrintMax, PrintGray, Compress, CompressMax. Values are case-sensitive as listed.	`web`
`async`	Optional	boolean	Lowercase JSON boolean. true returns 202 plus a Location URL to poll, for large files. false or omitted returns the linearized PDF directly on 200.	`true`

Sample payloads

Linearize for web viewing

{
 "docContent": "JVBERi0xLjcKJb...",
 "docName": "report.pdf",
 "optimizeProfile": "web"
}

Large file, asynchronous

{
 "docContent": "JVBERi0xLjcKJb...",
 "docName": "catalog-2026.pdf",
 "optimizeProfile": "WebMax",
 "async": true
}

Postman collection tips

Headers

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

Body

raw JSON with docContent, docName, optimizeProfile, and optionally async (lowercase, boolean).

Response

On 200, use "Send and Download": the body is the PDF itself, not JSON.

Async

With async true, copy the Location header from the 202 response into a GET request and poll it every ~10 seconds until 200.

curl example

curl -X POST https://api.pdf4me.com/api/v2/LinearizePdf \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic YOUR_API_KEY" \
 -d '{
 "docContent": "'"$(base64 -w 0 report.pdf)"'",
 "docName": "report.pdf",
 "optimizeProfile": "web"
 }' \
 --output linearized.pdf

What does the API return?

Field	Type	What it contains
`200 response body`	Binary (application/pdf)	The linearized PDF as raw bytes. Save it directly. The official samples also handle a JSON-wrapped Base64 fallback, but binary is the primary contract.
`202 Location header`	URL	Async mode only: the polling URL. GET it about every 10 seconds (samples: 10 retries) until it returns 200 with the PDF bytes.
`4xx/5xx response body`	JSON or text	Error details: 400 for malformed Base64 or an unknown optimizeProfile value, 401 for a missing or invalid API key, 500 for server-side processing failures.

Code samples

Official, runnable samples for this exact endpoint, per language:

FAQ

What is a linearized PDF?+

A PDF whose internal objects are reordered so the first page and its resources sit at the front of the file. A viewer can render page 1 while the rest is still downloading, which is why linearization is also called fast web view.

Does linearization change how the PDF looks?+

No. Pages, text, and images stay identical. Only the internal object order and structure change so browsers and viewers can start rendering before the full file arrives.

Which optimizeProfile should I use for websites?+

Start with web. If load speed matters more than anything else, WebMax applies the most aggressive web optimization. The print and compress profiles target paper output and file size instead of progressive display.

Is the async flag called IsAsync?+

No. The official samples send it as lowercase async, a JSON boolean. Sending true switches the API to 202-plus-polling mode; false or omitting it returns the linearized PDF directly in the response body.

Is the response JSON with a Base64 file inside?+

Normally no: a 200 response body is the linearized PDF as raw bytes, ready to save. The official samples also defensively handle a JSON-wrapped Base64 variant, but the primary contract is binary.

How is this different from Compress PDF?+

Compress PDF exists to shrink file size. Linearize PDF exists to reorder the file for progressive display; the Compress and CompressMax profiles borrow some size reduction, but if pure size is the goal, use the dedicated Compress PDF endpoint.

Does my web server need special support?+

For the full benefit the server should support HTTP byte-range requests, which mainstream web servers and CDNs do by default. The linearized file still opens normally everywhere, even without range support.

Why linearize PDFs for the web?

A standard PDF stores its directory information at the end of the file, so a viewer must download essentially everything before rendering page 1. Linearized PDF, defined as a normative annex of the ISO 32000 specification, moves that directory and the first page to the front, enabling incremental access over HTTP. For a document portal or CDN, that turns a multi-second blank wait into a first page that appears while the rest streams in.

Compress PDF

When file size, not load order, is the problem to solve.

Create PDF/A

Long-term archival conversion instead of web delivery optimization.

Flatten PDF

Merge form fields and annotations into page content before publishing.