Merge PDF documents, interleave pages, extract or delete selected pages, and apply watermarks or document settings with a direct HTTP request from any language or platform. For language-specific client libraries, see the SDK guides.
| Request | Details |
|---|---|
| Method and endpoint | POST https://api.pdfcrowd.com/convert/24.04/ |
| Authentication | HTTP Basic: your PDFCrowd username and API key |
| Request body | Form fields; use multipart form data for file uploads |
| Successful response | 200 OK with the PDF bytes in the response body |
Choose an operation below. You can run the examples below with the displayed API credentials. Update the input URLs and filenames as needed.
Each example saves the returned PDF to a local file. If a conversion fails, inspect the response for error details.
Use a Bash-compatible shell.
Basic options
-u — Supply your username and API key.-F — Send a form field.-o — Save the response to a file.-f — Report HTTP errors as command failures.-s -S — Hide the progress meter while keeping error messages.File input
f_1=@document.pdf — Upload a local file.Diagnostics
--fail-with-body
— Use instead of -f to retain the error response body.
-D — Save response headers to a file.-w — Print response information;
the diagnostic example
prints the HTTP status.
Install Requests with
python3 -m pip install requests. Save an example as
convert.py and run it with python3 convert.py.
Request options
auth — Supply your username and API key using HTTP Basic authentication.data — Send form fields; Requests encodes their values.files — Upload files opened in binary mode. Requests sets the multipart boundary.allow_redirects=False — Return the endpoint's response without following redirects.Response handling
raise_for_status() — Raise an exception for HTTP errors before opening the output file.response.content — Save the response bytes to a file opened with "wb".with — Close opened files even if the request or output write fails.
Connection errors raise exceptions. The examples do not set a client timeout or
retry requests. If you add a timeout, allow for conversion time;
Requests applies connection and read timeouts, not an overall conversion deadline.
The diagnostic example
saves response headers and body and prints the HTTP status before calling
raise_for_status(), so an HTTP error still leaves diagnostic files.
Use Node.js with its built-in Fetch API; no HTTP package is needed.
Save an example as convert.mjs and run it with
node convert.mjs. The .mjs extension enables imports
and top-level await.
Request options
Authorization — Send your username and API key using HTTP Basic authentication.FormData — Send form fields and files. Fetch sets the multipart boundary.readFile and Blob — Read uploads as bytes into memory and include their filenames.redirect: 'manual' — Return the endpoint's response without following redirects.Response handling
response.arrayBuffer() — Read the response bytes into memory.response.status — Check for HTTP errors before opening the output file; Fetch does not throw for HTTP errors itself.writeFile — Save the bytes to the output file. File and connection errors propagate as exceptions.
The examples use Fetch's native connection, response-header, and body inactivity
limits, which depend on the Node.js runtime. They do not set an overall conversion
deadline or retry requests. Allow for conversion time if you add a timeout using
an AbortSignal.
The diagnostic example saves response headers and body and prints the HTTP status before throwing on an HTTP error, so diagnostic files remain available.
Install Axios with npm install axios. Save an example as
convert.mjs and run it with node convert.mjs.
The .mjs extension enables imports and top-level await.
Request options
auth — Send your username and API key using HTTP Basic authentication.FormData — Send form fields and files. Axios sets the multipart boundary.readFile and Blob — Read uploads as bytes into memory and include their filenames.maxRedirects: 0 — Return the endpoint's response without following redirects.Response handling
responseType: 'arraybuffer' — Read the response as bytes.validateStatus — Reject HTTP errors before writing the output file.writeFile — Save the response bytes to the output file.Axios does not set an overall timeout by default. Allow for conversion time if you add one. Failed requests and file writes produce an error message and a nonzero exit status; the error handler prints only the message so request credentials are not included.
The diagnostic example saves response headers and body and prints the HTTP status before reporting an HTTP error, so diagnostic files remain available.
Install Guzzle with composer require guzzlehttp/guzzle.
Save an example as convert.php beside your vendor
directory and run it with php convert.php.
Request options
auth — Send your username and API key using HTTP Basic authentication.multipart — Send form fields and files. Guzzle sets the multipart boundary.Utils::tryFopen — Open input files as binary streams for upload.'allow_redirects' => false — Return the endpoint's response without following redirects.Response handling
'http_errors' => false — Inspect the HTTP status before writing the output file.getBody — Read the response as a binary string.file_put_contents — Save the response bytes and check that the entire result was written.Guzzle does not set an overall timeout by default. Allow for conversion time if you add one. Failed requests and file writes produce an error message and a nonzero exit status.
The diagnostic example saves response headers and body and prints the HTTP status before reporting an HTTP error, so diagnostic files remain available.
Upload the PDFs as numbered file fields. This example combines a cover,
proposal, price list and contact page into offer.pdf.
Replace the paths with your local files:
curl -f -s -S \ -u 'demo:demo' \ -o offer.pdf \ -F f_1=@cover.pdf \ -F f_2=@proposal.pdf \ -F f_3=@price.pdf \ -F f_4=@contact.pdf \ -F input_format=pdf \ https://api.pdfcrowd.com/convert/24.04/
import requests with ( open('cover.pdf', 'rb') as input_1, open('proposal.pdf', 'rb') as input_2, open('price.pdf', 'rb') as input_3, open('contact.pdf', 'rb') as input_4, ): response = requests.post( 'https://api.pdfcrowd.com/convert/24.04/', auth=('demo', 'demo'), data={ 'input_format': 'pdf', }, files={ 'f_1': input_1, 'f_2': input_2, 'f_3': input_3, 'f_4': input_4, }, allow_redirects=False, ) response.raise_for_status() with open('offer.pdf', 'wb') as output_file: output_file.write(response.content)
import { readFile, writeFile } from 'node:fs/promises'; import { basename } from 'node:path'; const username = 'demo'; const apiKey = 'demo'; const form = new FormData(); form.append("input_format", "pdf"); form.append("f_1", new Blob([await readFile("cover.pdf")]), basename("cover.pdf")); form.append("f_2", new Blob([await readFile("proposal.pdf")]), basename("proposal.pdf")); form.append("f_3", new Blob([await readFile("price.pdf")]), basename("price.pdf")); form.append("f_4", new Blob([await readFile("contact.pdf")]), basename("contact.pdf")); const response = await fetch("https://api.pdfcrowd.com/convert/24.04/", { method: 'POST', headers: { Authorization: 'Basic ' + Buffer.from( username + ':' + apiKey).toString('base64'), }, body: form, redirect: 'manual', }); const body = Buffer.from(await response.arrayBuffer()); if (response.status >= 400) { throw new Error('HTTP ' + response.status + ' ' + response.statusText); } await writeFile("offer.pdf", body);
import axios from 'axios'; import { readFile, writeFile } from 'node:fs/promises'; import { basename } from 'node:path'; const username = 'demo'; const apiKey = 'demo'; const form = new FormData(); form.append("input_format", "pdf"); form.append("f_1", new Blob([await readFile("cover.pdf")]), basename("cover.pdf")); form.append("f_2", new Blob([await readFile("proposal.pdf")]), basename("proposal.pdf")); form.append("f_3", new Blob([await readFile("price.pdf")]), basename("price.pdf")); form.append("f_4", new Blob([await readFile("contact.pdf")]), basename("contact.pdf")); try { const response = await axios.post("https://api.pdfcrowd.com/convert/24.04/", form, { auth: { username, password: apiKey }, responseType: 'arraybuffer', maxRedirects: 0, validateStatus: status => status < 400, }); await writeFile("offer.pdf", response.data); } catch (error) { console.error(error.message); process.exitCode = 1; }
<?php require 'vendor/autoload.php'; use GuzzleHttp\Client; use GuzzleHttp\Psr7\Utils; try { $client = new Client(); $response = $client->post('https://api.pdfcrowd.com/convert/24.04/', [ 'auth' => ['demo', 'demo'], 'multipart' => [ ['name' => 'input_format', 'contents' => 'pdf'], ['name' => 'f_1', 'contents' => Utils::tryFopen('cover.pdf', 'rb'), 'filename' => basename('cover.pdf')], ['name' => 'f_2', 'contents' => Utils::tryFopen('proposal.pdf', 'rb'), 'filename' => basename('proposal.pdf')], ['name' => 'f_3', 'contents' => Utils::tryFopen('price.pdf', 'rb'), 'filename' => basename('price.pdf')], ['name' => 'f_4', 'contents' => Utils::tryFopen('contact.pdf', 'rb'), 'filename' => basename('contact.pdf')], ], 'allow_redirects' => false, 'http_errors' => false, ]); $status = $response->getStatusCode(); if ($status >= 400) { throw new \RuntimeException("HTTP $status " . $response->getReasonPhrase()); } $body = (string) $response->getBody(); if (file_put_contents('offer.pdf', $body) !== strlen($body)) { throw new \RuntimeException('Failed to write output file'); } } catch (\Throwable $error) { fwrite(STDERR, $error->getMessage() . "\n"); exit(1); }
Merging is the default operation. The numeric suffix determines the order:
all pages from f_1 come first, followed by f_2,
and so on. Add or remove numbered fields to match your documents.
Upload the source PDF as f_1 and the watermark PDF as
page_watermark. This example saves the result in
company_offer.pdf:
curl -f -s -S \ -u 'demo:demo' \ -o company_offer.pdf \ -F page_watermark=@watermark.pdf \ -F f_1=@proposal.pdf \ -F input_format=pdf \ https://api.pdfcrowd.com/convert/24.04/
import requests with ( open('watermark.pdf', 'rb') as input_1, open('proposal.pdf', 'rb') as input_2, ): response = requests.post( 'https://api.pdfcrowd.com/convert/24.04/', auth=('demo', 'demo'), data={ 'input_format': 'pdf', }, files={ 'page_watermark': input_1, 'f_1': input_2, }, allow_redirects=False, ) response.raise_for_status() with open('company_offer.pdf', 'wb') as output_file: output_file.write(response.content)
import { readFile, writeFile } from 'node:fs/promises'; import { basename } from 'node:path'; const username = 'demo'; const apiKey = 'demo'; const form = new FormData(); form.append("input_format", "pdf"); form.append("page_watermark", new Blob([await readFile("watermark.pdf")]), basename("watermark.pdf")); form.append("f_1", new Blob([await readFile("proposal.pdf")]), basename("proposal.pdf")); const response = await fetch("https://api.pdfcrowd.com/convert/24.04/", { method: 'POST', headers: { Authorization: 'Basic ' + Buffer.from( username + ':' + apiKey).toString('base64'), }, body: form, redirect: 'manual', }); const body = Buffer.from(await response.arrayBuffer()); if (response.status >= 400) { throw new Error('HTTP ' + response.status + ' ' + response.statusText); } await writeFile("company_offer.pdf", body);
import axios from 'axios'; import { readFile, writeFile } from 'node:fs/promises'; import { basename } from 'node:path'; const username = 'demo'; const apiKey = 'demo'; const form = new FormData(); form.append("input_format", "pdf"); form.append("page_watermark", new Blob([await readFile("watermark.pdf")]), basename("watermark.pdf")); form.append("f_1", new Blob([await readFile("proposal.pdf")]), basename("proposal.pdf")); try { const response = await axios.post("https://api.pdfcrowd.com/convert/24.04/", form, { auth: { username, password: apiKey }, responseType: 'arraybuffer', maxRedirects: 0, validateStatus: status => status < 400, }); await writeFile("company_offer.pdf", response.data); } catch (error) { console.error(error.message); process.exitCode = 1; }
<?php require 'vendor/autoload.php'; use GuzzleHttp\Client; use GuzzleHttp\Psr7\Utils; try { $client = new Client(); $response = $client->post('https://api.pdfcrowd.com/convert/24.04/', [ 'auth' => ['demo', 'demo'], 'multipart' => [ ['name' => 'input_format', 'contents' => 'pdf'], ['name' => 'page_watermark', 'contents' => Utils::tryFopen('watermark.pdf', 'rb'), 'filename' => basename('watermark.pdf')], ['name' => 'f_1', 'contents' => Utils::tryFopen('proposal.pdf', 'rb'), 'filename' => basename('proposal.pdf')], ], 'allow_redirects' => false, 'http_errors' => false, ]); $status = $response->getStatusCode(); if ($status >= 400) { throw new \RuntimeException("HTTP $status " . $response->getReasonPhrase()); } $body = (string) $response->getBody(); if (file_put_contents('company_offer.pdf', $body) !== strlen($body)) { throw new \RuntimeException('Failed to write output file'); } } catch (\Throwable $error) { fwrite(STDERR, $error->getMessage() . "\n"); exit(1); }
The first page of the watermark PDF is placed over every page of the source PDF. You can also apply a watermark when merging several PDFs in one request.
Use your PDFCrowd username as the HTTP Basic username and your API key as the password. Configure these credentials using your HTTP client's Basic authentication option.
Find and manage your credentials on the API Keys page.
Send the input and conversion settings as form fields in a POST request. JSON request bodies are not supported. Your HTTP client handles form encoding and the appropriate headers.
Use the versioned endpoint: https://api.pdfcrowd.com/convert/24.04/.
Keep the version explicit in your integration and review
API versioning before changing it.
Errors are returned as plain text by default; add ?errfmt=json
to the endpoint to receive JSON errors. This changes only the error format;
a successful response still contains the converted PDF.
See Handle the Response for response handling.
Set input_format
to pdf. Upload each PDF as a file in a multipart form request,
using fields named f_1, f_2, f_3, and so on.
The output is a PDF by default.
Files are processed in numeric field order, regardless of their filenames or the order of fields in the request. Send the file contents, not a local path or URL as a text value. If your PDF is hosted at a URL, download it in your application and upload it in one of these fields.
Set the action
form field to choose how the input PDFs are processed:
| Action | Result |
|---|---|
join (default) |
Merge the PDFs in numeric field order, keeping each document's pages together. With one input, use this to apply settings such as a watermark or password. |
shuffle |
Interleave pages from the inputs: page 1 from each PDF, then page 2 from each, and so on. |
extract |
Keep the pages selected by page_range. Supply one input PDF in f_1. |
delete |
Remove the pages selected by page_range. Supply one input PDF in f_1. |
For extraction or deletion, set
page_range
to the pages you want to target. Page numbers start at 1; for example,
1,3-5 selects pages 1, 3, 4 and 5. Each request performs one
operation and returns one PDF.
Send settings as additional form fields alongside your input PDFs and operation. Common options include:
| Purpose | Options |
|---|---|
| Open password-protected inputs | input_pdf_password; the same password is used for all input PDFs. |
| Add a watermark or background | page_watermark, page_background, multipage_watermark |
| Protect the output PDF | user_password, owner_password, no_print, no_copy |
| Set document metadata | title, author, use_metadata_from |
| Optimize for viewing online | linearize |
| Embed attachments | attachment; use numbered attachment_1, attachment_2, … fields for multiple files. |
The parameter reference lists all settings, accepted values, defaults, and constraints. For complete conversion requests, see the HTTP examples.
A successful conversion returns 200 OK,
Content-Type: application/pdf, and the
PDF bytes in the
response body. Save those bytes to a file or return them to your application's
user.
An illustrative response is:
HTTP/1.1 200 OK Content-Type: application/pdf x-pdfcrowd-job-id: example-job-id x-pdfcrowd-pages: 1 [PDF bytes]
Check the HTTP status before processing the body. Treat a successful response as binary data; parsing it as JSON or decoding it as text will not produce a usable PDF.
An unsuccessful request returns an error HTTP status. PDFCrowd error responses also include a reason code that identifies the specific problem.
By default, the error body is plain text in this format:
<status_code>.<reason_code> - <message>
For structured errors, append ?errfmt=json to the endpoint:
https://api.pdfcrowd.com/convert/24.04/?errfmt=json
An example JSON error body for missing conversion input is:
{
"status_code": 400,
"reason_code": 325,
"message": "There is no input specified to be converted."
}
PDFCrowd JSON errors use Content-Type: application/json. A
successful request still returns a PDF
when errfmt=json is set. If a failed response has a different
content type, retain its body and status for diagnosis instead of assuming
it is JSON.
| Status | What it means | What to do |
|---|---|---|
400 |
Invalid request or conversion failure | Read the reason code and correct the input or settings. |
401 |
Missing credentials or an inactive license | Check your username, API key, and license status. |
403 |
Suspended service or no credits remaining | Check your account and available credits. |
413 |
Upload exceeds the 300 MB limit | Reduce the upload size. |
429 |
Request rate limit reached | Wait and reduce the rate of new requests. |
430 |
Concurrent request limit reached | Allow active requests to finish before starting more. |
503 |
Temporary network issue | Retry after a delay. |
See all status and reason codes for specific error explanations. For request limits and retry guidance, see Limits and Retries.
Use these headers, when present, to record conversion results and diagnose problems:
| Header | Use |
|---|---|
x-pdfcrowd-job-id |
Identify the conversion in logs and support requests. |
x-pdfcrowd-reason-code |
Read the error reason code; 0 indicates success. |
x-pdfcrowd-debug-log |
Open the debug log when debug logging is enabled. |
x-pdfcrowd-consumed-credits |
Record credits consumed by this conversion. |
x-pdfcrowd-remaining-credits |
Monitor the remaining account balance. |
x-pdfcrowd-pages |
Read the output PDF's page count. |
x-pdfcrowd-output-size |
Read the output size in bytes. |
Request rate and concurrency limits depend on your license. Control how
quickly you submit conversions and how many you run at once. A 429
response concerns request rate; a 430 response concerns requests
already in progress.
The maximum upload size is 300 MB.
For temporary failures, use a bounded number of retries with increasing delays. Correct invalid input, authentication, or account problems before retrying those requests.
If a conversion exceeds 60 seconds of processing time, PDFCrowd stops it and returns an error response.
Capture the HTTP status, response headers, and response body when diagnosing
a request. Set debug_log to true to enable a
conversion debug log, and add errfmt=json to the endpoint's
query string for structured error details. Use the input and conversion
settings from the request you're investigating.
curl --fail-with-body \ -u 'demo:demo' \ -D response.headers \ -o response.body \ -w 'HTTP %{http_code}\n' \ -F f_1=@cover.pdf \ -F f_2=@proposal.pdf \ -F input_format=pdf \ -F debug_log=true \ 'https://api.pdfcrowd.com/convert/24.04/?errfmt=json'
import requests with ( open('cover.pdf', 'rb') as input_1, open('proposal.pdf', 'rb') as input_2, ): response = requests.post( 'https://api.pdfcrowd.com/convert/24.04/?errfmt=json', auth=('demo', 'demo'), data={ 'input_format': 'pdf', 'debug_log': 'true', }, files={ 'f_1': input_1, 'f_2': input_2, }, allow_redirects=False, ) with open('response.headers', 'w', encoding='utf-8') as headers_file: for name, value in response.headers.items(): headers_file.write(f'{name}: {value}\n') with open('response.body', 'wb') as output_file: output_file.write(response.content) print(f'HTTP {response.status_code}') response.raise_for_status()
import { readFile, writeFile } from 'node:fs/promises'; import { basename } from 'node:path'; const username = 'demo'; const apiKey = 'demo'; const form = new FormData(); form.append("input_format", "pdf"); form.append("debug_log", "true"); form.append("f_1", new Blob([await readFile("cover.pdf")]), basename("cover.pdf")); form.append("f_2", new Blob([await readFile("proposal.pdf")]), basename("proposal.pdf")); const response = await fetch("https://api.pdfcrowd.com/convert/24.04/?errfmt=json", { method: 'POST', headers: { Authorization: 'Basic ' + Buffer.from( username + ':' + apiKey).toString('base64'), }, body: form, redirect: 'manual', }); const body = Buffer.from(await response.arrayBuffer()); await writeFile("response.headers", Array.from(response.headers, ([name, value]) => name + ': ' + value ).join('\n') + '\n'); await writeFile("response.body", body); console.log('HTTP ' + response.status); if (response.status >= 400) { throw new Error('HTTP ' + response.status + ' ' + response.statusText); }
import axios from 'axios'; import { readFile, writeFile } from 'node:fs/promises'; import { basename } from 'node:path'; const username = 'demo'; const apiKey = 'demo'; const form = new FormData(); form.append("input_format", "pdf"); form.append("debug_log", "true"); form.append("f_1", new Blob([await readFile("cover.pdf")]), basename("cover.pdf")); form.append("f_2", new Blob([await readFile("proposal.pdf")]), basename("proposal.pdf")); try { const response = await axios.post("https://api.pdfcrowd.com/convert/24.04/?errfmt=json", form, { auth: { username, password: apiKey }, responseType: 'arraybuffer', maxRedirects: 0, validateStatus: () => true, }); await writeFile("response.headers", response.headers.toString() + '\n'); await writeFile("response.body", response.data); console.log('HTTP ' + response.status); if (response.status >= 400) { throw new Error('HTTP ' + response.status + ' ' + response.statusText); } } catch (error) { console.error(error.message); process.exitCode = 1; }
<?php require 'vendor/autoload.php'; use GuzzleHttp\Client; use GuzzleHttp\Psr7\Utils; try { $client = new Client(); $response = $client->post('https://api.pdfcrowd.com/convert/24.04/?errfmt=json', [ 'auth' => ['demo', 'demo'], 'multipart' => [ ['name' => 'input_format', 'contents' => 'pdf'], ['name' => 'debug_log', 'contents' => 'true'], ['name' => 'f_1', 'contents' => Utils::tryFopen('cover.pdf', 'rb'), 'filename' => basename('cover.pdf')], ['name' => 'f_2', 'contents' => Utils::tryFopen('proposal.pdf', 'rb'), 'filename' => basename('proposal.pdf')], ], 'allow_redirects' => false, 'http_errors' => false, ]); $status = $response->getStatusCode(); $headers = ''; foreach ($response->getHeaders() as $name => $values) { $headers .= $name . ": " . implode(", ", $values) . "\n"; } if (file_put_contents('response.headers', $headers) !== strlen($headers)) { throw new \RuntimeException('Failed to write response headers'); } $body = (string) $response->getBody(); if (file_put_contents('response.body', $body) !== strlen($body)) { throw new \RuntimeException('Failed to write output file'); } echo "HTTP $status\n"; if ($status >= 400) { throw new \RuntimeException("HTTP $status " . $response->getReasonPhrase()); } } catch (\Throwable $error) { fwrite(STDERR, $error->getMessage() . "\n"); exit(1); }
Check the HTTP status before interpreting the body. A successful response contains PDF bytes; an unsuccessful response should be inspected for error details. If no HTTP response arrives, check the error reported by your HTTP client.
The x-pdfcrowd-debug-log header links to diagnostic information
about the conversion. You can also find logs in your
conversion history.
| Problem | Check |
|---|---|
| No input or an invalid PDF | Upload nonempty PDF files in numbered fields such as f_1 and f_2. A local path or URL sent as a text value does not upload a file. |
| Documents appear in the wrong order | Check the numeric suffixes of the f_1, f_2, … fields. Use action=join to keep each document together or action=shuffle to interleave their pages. |
| Page extraction or deletion fails | Supply one PDF and check page_range against its page count. Page numbers start at 1. |
| A password-protected input cannot be opened | Set input_pdf_password to the password for the input PDFs. The user_password setting protects the output PDF instead. |
| The same watermark appears on every page | page_watermark repeats the watermark PDF's first page. Use multipage_watermark to apply corresponding pages from a multi-page watermark PDF. |
| The HTTP client times out before receiving the response | Check its timeout settings and allow enough time for conversion, uploading the input, and downloading the result. |
For help, contact support and include any available diagnostics and enough detail for us to reproduce the problem.