PDF to PDF HTTP API

Overview

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.

Quick Start

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 uses cURL and saves the returned PDF to a local file. If a conversion fails, inspect the response for error details.

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/

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/

Build a Request

Authentication

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.

Request Format

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.

Supply Input PDFs

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.

Choose an Operation

Set the action form field to choose how the input PDFs are processed:

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.

Add Conversion Settings

Send settings as additional form fields alongside your input PDFs and operation. Common options include:

The parameter reference lists all settings, accepted values, defaults, and constraints. For complete conversion requests, see the HTTP examples.

Handle the Response

Successful Conversion

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.

Errors

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.

Common Status Codes

See all status and reason codes for specific error explanations. For request limits and retry guidance, see Limits and Retries.

Response Headers

Use these headers, when present, to record conversion results and diagnose problems:

Limits and Retries

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.

Troubleshooting

Inspect a Request

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'

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.

Common Problems

For help, contact support and include any available diagnostics and enough detail for us to reproduce the problem.