API v2 migration guide

Migrate an existing HTML-to-PDF integration from API v1 to API v2 while keeping your current integration available during testing. API v2 uses a newer rendering engine, so compare the generated PDFs as well as updating your code.

1. Open your API v2 license page and activate a trial if available. If your account previously had a v2 license and no trial option is shown, contact support about testing access.
2. Update a test copy of your integration using the examples and mappings below. Keep API v1 running while you test API v2.
3. Choose an API v2 plan that covers your usage and switch production to the tested integration. API v1 and API v2 have separate licenses; purchasing a v2 plan does not cancel your v1 subscription.
4. Once you no longer need API v1, cancel its subscription from your API v1 license page.

API client libraries

Install the latest client library for your language. You can run both integrations under the same PDFCrowd account. Each API needs its own active license or trial.

Migrate the client constructor, conversion method, conversion settings, and error handling together. The examples below use placeholder credentials; replace them with your PDFCrowd username and API key.

Client instantiation

These fragments show the old and new client classes. The v2 guides cover PHP, Java, .NET, Ruby, Python, and Node.js.

// PHP
$client_v1 = new Pdfcrowd("username", "apikey");
$client_v2 = new \Pdfcrowd\HtmlToPdfClient("username", "apikey");

// Java: import com.pdfcrowd.Client and com.pdfcrowd.Pdfcrowd.
Client client_v1 = new Client("username", "apikey");
Pdfcrowd.HtmlToPdfClient client_v2 =
    new Pdfcrowd.HtmlToPdfClient("username", "apikey");

// .NET
pdfcrowd.Client client_v1 = new pdfcrowd.Client("username", "apikey");
pdfcrowd.HtmlToPdfClient client_v2 =
    new pdfcrowd.HtmlToPdfClient("username", "apikey");

# Ruby
client_v1 = Pdfcrowd::Client.new("username", "apikey")
client_v2 = Pdfcrowd::HtmlToPdfClient.new("username", "apikey")

# Python
client_v1 = pdfcrowd.Client("username", "apikey")
client_v2 = pdfcrowd.HtmlToPdfClient("username", "apikey")

// Node.js
const pdfcrowd = require("pdfcrowd");
const client_v1 = new pdfcrowd.Pdfcrowd("username", "apikey");
const client_v2 = new pdfcrowd.HtmlToPdfClient("username", "apikey");

API mapping

Read the method or option in each API column for your integration:

• SDKs with v1 setter methods: API v1 method → API v2 method.
• Node.js v1 options: API v1 option → API v2 method.
• HTTP requests: API v1 option → API v2 option.

Method names below use camelCase; follow your SDK's naming convention. Method links open the index for all languages. A dash means there is no corresponding method or option.

For conversion calls, choose PDF data, a local output file (ToFile), or a stream (ToStream); return values and stream arguments vary by SDK. HTTP returns the PDF in the response. For enableImages, enableBackgrounds, and enableJavaScript, invert the method argument; the corresponding v1 options already express disabling, so their values stay unchanged.

You can also use setPageMargins to set all four margins together, in top, right, bottom, left order.

PHP example

For example, an API v1 integration might set landscape dimensions and numeric margins before writing a PDF:

$client_v1 = new Pdfcrowd("username", "apikey");
$client_v1->setPageWidth("11in");
$client_v1->setPageHeight("8.5in");
$client_v1->setPageMargins(36, 36, 36, 36);
$client_v1->usePrintMedia(true);
$client_v1->convertURI("https://example.com/", fopen("example.pdf", "wb"));

Here is the corresponding API v2 script. Download pdfcrowd.php using the PHP installation instructions and place it beside the script. If you use Composer, load vendor/autoload.php instead.

<?php
require __DIR__ . '/pdfcrowd.php';

try {
    $client = new \Pdfcrowd\HtmlToPdfClient("username", "apikey");
    $client->setPageSize("Letter");
    $client->setOrientation("landscape");
    $client->setPageMargins("36pt", "36pt", "36pt", "36pt");
    $client->setUsePrintMedia(true);
    $client->convertUrlToFile("https://example.com/", "example.pdf");
} catch (\Pdfcrowd\Error $error) {
    error_log((string) $error);
    exit(1);
} catch (\Throwable $error) {
    error_log($error->getMessage());
    exit(1);
}

The settings preserve the page dimensions, margins, and print-media choice. API v2 PHP errors use \Pdfcrowd\Error; replace v1 PdfcrowdException handlers as shown above.

Node.js example

The v1 client receives an options object; the v2 client uses setter methods. Find the option under API v1 and use the method under API v2 in the mapping table. This example uses CommonJS and preserves callback-based control flow.

// API v1
const pdfcrowd = require("pdfcrowd");
const client_v1 = new pdfcrowd.Pdfcrowd("username", "apikey");

client_v1.convertURI(
    "https://example.com/",
    pdfcrowd.saveToFile("example.pdf"),
    {
        width: "11in",
        height: "8.5in",
        use_print_media: true,
    }
);

// API v2
const pdfcrowd = require("pdfcrowd");

try {
    const client_v2 = new pdfcrowd.HtmlToPdfClient("username", "apikey");
    client_v2.setPageSize("Letter");
    client_v2.setOrientation("landscape");
    client_v2.setUsePrintMedia(true);

    client_v2.convertUrlToFile(
        "https://example.com/",
        "example.pdf",
        function (error, fileName) {
            if (error) {
                console.error(String(error));
                process.exitCode = 1;
                return;
            }
            console.log("Saved:", fileName);
        }
    );
} catch (error) {
    console.error(String(error));
    process.exitCode = 1;
}

HTTP access

Send API v2 requests to https://api.pdfcrowd.com/convert/24.04/ to use the latest converter. Use HTTP Basic authentication: your PDFCrowd username is the username, and your API key is the password. Send form fields rather than JSON; use multipart form data for uploads.

These cURL examples use a Bash-compatible shell. The -f option makes HTTP errors fail the command; -s -S hides the progress meter while retaining error messages. Check the exit status before using the output file. For diagnostics that retain the error response body, see HTTP error handling.

Convert a URL

# API v1
curl -f -s -S \
  -F 'username=username' -F 'key=apikey' \
  -F 'src=https://example.com/' \
  -o example.pdf \
  'https://pdfcrowd.com/api/pdf/convert/uri/'

# API v2
curl -f -s -S -u 'username:apikey' \
  -F 'url=https://example.com/' \
  -o example.pdf \
  'https://api.pdfcrowd.com/convert/24.04/'

Convert a file

Both commands read an existing local file named example.html.

# API v1
curl -f -s -S \
  -F 'username=username' -F 'key=apikey' \
  -F 'src=@example.html' \
  -o example.pdf \
  'https://pdfcrowd.com/api/pdf/convert/html/'

# API v2
curl -f -s -S -u 'username:apikey' \
  -F 'file=@example.html' \
  -o example.pdf \
  'https://api.pdfcrowd.com/convert/24.04/'

Convert an HTML string

Use --form-string for literal HTML. With -F, a leading < means “read a local file,” so -F 'text=<html>...' does not send the HTML as a string.

# API v1
curl -f -s -S \
  -F 'username=username' -F 'key=apikey' \
  --form-string 'src=<html><body><h1>Hello World!</h1></body></html>' \
  -o hello.pdf \
  'https://pdfcrowd.com/api/pdf/convert/html/'

# API v2
curl -f -s -S -u 'username:apikey' \
  --form-string 'text=<html><body><h1>Hello World!</h1></body></html>' \
  -o hello.pdf \
  'https://api.pdfcrowd.com/convert/24.04/'

For HTML strings, use absolute resource URLs or an HTML <base> element. If the HTML uses local images or stylesheets, see including local assets.

Setting and rendering changes

Headers and footers

Replace the v1 placeholders with HTML elements carrying these classes:

• %u → pdfcrowd-source-url
• %p → pdfcrowd-page-number
• %n → pdfcrowd-page-count

<!-- API v1 -->
Page %p of %n.

<!-- API v2 -->
Page <span class="pdfcrowd-page-number"></span> of
<span class="pdfcrowd-page-count"></span>.

API v1 places headers and footers in the page margins. API v2 places them inside the printing area. Set setHeaderHeight() and setFooterHeight() to reserve the required space.

Units

V1 accepts unitless dimensions as points (1/72 inch). In v2, write ordinary dimensions with an explicit pt, in, mm, cm, or px suffix. For example, convert a v1 margin of 36 to "36pt" or "0.5in", not "36px". Use 0 for zero margins and "-1" for a page height that expands to fit the content.

PDF viewer settings

For page_layout, replace SINGLE_PAGE / 1 with "single-page" and CONTINUOUS / 2 with "one-column". For CONTINUOUS_FACING / 3, choose "two-column-left" or "two-column-right" to match the intended facing-page layout.

For page_mode, replace THUMBNAILS_VISIBLE / 2 with "thumbnails" and FULLSCREEN / 3 with "full-screen". For NONE_VISIBLE / 1, omit the setting.

For the initial zoom type, replace FIT_WIDTH / 1, FIT_HEIGHT / 2, and FIT_PAGE / 3 with "fit-width", "fit-height", and "fit-page". For an exact zoom (4), omit the zoom type and pass the percentage to setInitialZoom or initial_zoom.

Watermarks and backgrounds

For a remote watermark, replace setWatermark(url) with setPageWatermarkUrl(url). If the v1 code also sets setWatermarkInBackground(true), use setPageBackgroundUrl(url) instead. Do not pass the old boolean to a method that expects a file or URL.

The setPageWatermark() and setPageBackground() variants accept local files. API v2 supports PDFs and images; use the multipage variants when different pages need different overlays.

Requests and usage

V1's fail_on_non200 becomes two settings: fail_on_main_url_error covers the source page, and fail_on_any_url_error covers its resources. Set both to fail on either kind of error. The corresponding setters are linked in the mapping table.

Replace numTokens() with getRemainingCreditCount() after a successful conversion. The v2 method reads response metadata; it does not make a separate balance request.

Settings without a direct rename

Legacy options such as HTML zoom, hyperlink disabling, transparent backgrounds, watermark offsets/rotation, and the PDFCrowd logo flag have no direct v2 rename. The reference and method index list the available v2 settings.