HTML to PDF conversion API

	Professional	Enterprise
Price	€ 50.00 / month or € 500.00 / year	€ 150.00 / month or € 1,500.00 / year
Monthly conversions	10,000	50,000

	Price	Monthly conversions
Professional	€ 50.00 / month or € 500.00 / year	10,000
Enterprise	€ 150.00 / month or € 1,500.00 / year	50,000

API endpoints & authentication

Quick information

API host:	html2pdf.appbeat.io
Protocol:	HTTPS
PDF conversion API:	/API/v1/conversion contains methods for asynchronous & synchronous PDF conversion
Management API:	/API/v1/management optional for managing crypto keys to protect PDF conversion payload
Authentication:	via request Authorization header (see below for details)
API specification:	Swagger
Structure descriptions:	Detailed JSON structure descriptions are available in topics below. See asynchronous and synchronous HTML to PDF conversions for more details.

Used HTTP status codes:

2xx: success
3xx: synchronous PDF conversion (download method) will use redirections while waiting for your PDF to convert & upload to AWS S3. If possible, use short client-side delays for each redirect.
4xx: error - we can't process your request, please check error details in response
5xx: error - something went wrong while processing your request, please check error details in response. If we send 503 you can retry request after some delay.

Our web service methods require authentication via request headers. In each request you will have to send your API Access Key & signed string via Authorization header:

Authorization: AppBeat YourAccessKeyId:StringToSign:Signature

Where:

Authorization = "AppBeat" + " " + YourAccessKeyId + ":" + StringToSign + ":" + Signature;
YourAccessKeyId is public API key that we generate for you (request your API key)
StringToSign = "v1" + "," + UnixTimeInSeconds;
Signature = Base64( HMAC-SHA-256( YourSecretAccessKey, ASCII-Encoding-Of( StringToSign ) ) );
YourSecretAccessKey is private secret used for signature generation and verification on our side. You should never share Secret Access Key with anyone!

Example: If your API Access Key Id is TestKeyId, Secret Access Key is TestSecret and current Unix time in seconds is 1580633761, you should send following Authorization header:

Authorization: AppBeat TestKeyId:v1,1580633761:4H3UzCkLgxk76jjCS6afhihNa6zR/E7qY9vyuPbbN8U=

Asynchronous PDF conversion

This API allows you to submit HTML to PDF conversion job to queue and one of our servers will process it. You can query job status by calling statusUrl from response or receive webhook notification when conversion is finished.

Request structure

{
  "payload": {
    "deliveryOptions": {
      "webhookUrl" ^[*] 
Optional webhook URL where we send notification about successfully completed / failed PDF conversion.

      "deliveryTypes" ^[*] 
One or more PDF delivery types (please see examples for more details). Structure example:
[{"deliveryType":"S3","options":{ ... }},{"deliveryType":"Email","options":{ ... }}]

    },
    "deduplicationId" ^[*] 
Optional external ID to prevent multiple conversion calls for same document during last 24 hours. Max length: 36 characters.

    "htmlOptions": {
      "htmlTemplate" ^[*] 
HTML document which is converted to PDF. For example:

<html>
   <head>
      <!-- CSS styles, ... -->
   </head>
   <body>
      <!-- formatted content -->
   </body>
</html>

Note: if you use this field you can't use htmlTemplateUrl

      "htmlTemplateUrl" ^[*] 
External URL of HTML template which is converted to PDF. For example: https://example.com/Template.html

Note: if you use this field you can't use htmlTemplate

      "doNotContinueOnResourceDownloadError" ^[*] 
If there are 4xx or 5xx errors while loading template resources (external images, external scripts, external styles) do not continue with PDF covnersion because result may not look 'nice' (missing images, etc).
Possible values: null, true, false
Default value: false

      "data" ^[*] 
Optional collection of name/value pairs which are paired with your HTML template.

      "mediaType" ^[*] 
Selects CSS style for targeting media type.
Possible values: null, "Default", "Print", "Screen"
Default value: "Screen"

      "inlineCss" ^[*] 
Additional CSS style for your HTML document (optional). For example:

.myCssStyle {
   background-color: yellow;
   font-size: large;
}

#myElement {
   font-weight: bold;
}

      "renderBackground" ^[*] 
Should HTML background be included when creating PDF?
Possible values: null, true, false
Default value: true

      "scale" ^[*] 
Scaling factor between 0.2 and 4.0
Default value: 1.0

      "htmlHeaderTemplate" ^[*] 
Optional HTML template which is inserted into page header.
Possible variables: {{pageNumber}}, {{totalPages}}
Example: This is <b>header</b> text, page {{pageNumber}} of {{totalPages}}

      "htmlFooterTemplate" ^[*] 
Optional HTML template which is inserted into page footer.
Possible variables: {{pageNumber}}, {{totalPages}}
Example: This is <b>footer</b> text, page {{pageNumber}} of {{totalPages}}

    },
    "pdfOptions": {
      "pageOrientation" ^[*] 
Possible values: null, "Default", "Landscape", "Portrait"
Default value: "Portrait"

      "pageSize": { ^[*] 
You can set predefinedPageSize or custom width and height where you can use following unit values: "Centimeters", "Inches", "Millimeters"
Default value: {"pageSize":{"predefinedPageSize":"A4"}}

        "width": {
          "value"
          "unit"
        },
        "height": {
          "value"
          "unit"
        },
        "predefinedPageSize" ^[*] 
Possible predefinedPageSize values: null, "A0", "A1", "A2", "A3", "A4", "A5", "Default", "Ledger", "Legal", "Letter", "Tabloid"
Default value if width and height are not set: "A4"
Which is equivalent to: {"pageSize":{"width":{"value":210,"unit":"Millimeters"},"height":{"value":297,"unit":"Millimeters"}}}

      },
      "margin": { ^[*] 
Space between the text and the edge of your PDF document.
Possible unit values: "Centimeters", "Inches", "Millimeters"
Default value: {"margin":{"top":{"value":25.4,"unit":"Millimeters"},"bottom":{"value":25.4,"unit":"Millimeters"},"left":{"value":25.4,"unit":"Millimeters"},"right":{"value":25.4,"unit":"Millimeters"}}}

        "top": {
          "value"
          "unit"
        },
        "bottom": {
          "value"
          "unit"
        },
        "left": {
          "value"
          "unit"
        },
        "right": {
          "value"
          "unit"
        }
      }
    }
  },
  "encryptedPayload" ^[*] 
You can encrypt your entire payload structure with AES-256 key and save Base64 encoded string here.
If you use this option you must also set encryptedPayloadKeyDetails structure. Please see examples for more details.

  "encryptedPayloadKeyDetails": {
    "keyId" ^[*] 
Unique key id generated with /API/v1/management/create-crypto-key. Please see examples for more details. Must be present if you set encryptedPayload.

    "sharedKeyBase64" ^[*] 
Shared partial key generated with /API/v1/management/create-crypto-key method. It is used to dynamically reconstruct your key on our side so we can decrypt your payload. Must be present if you set encryptedPayload. Please see examples for more details.

    "ivBase64" ^[*] 
You can send us random initialization vector (IV) if you used non-zero value for payload encryption. When we decode it from Base64 it must be exactly 16 bytes long. If you don't send it we assume that you used IV with all zeroes.

  }
}

Response structure

{
  "status" ^[*] 
If conversion was successfully queued you will receive value ConversionQueued, otherwise you should receive ConversionNotQueued with more details in error field

  "jobId" ^[*] 
If conversion was successfully queued you will receive unique job identifier in this field

  "statusUrl" ^[*] 
You can use this URL to query current conversion status (you must also send Authorization header)

  "cancelUrl" ^[*] 
You can use this URL to cancel conversion job if it is still in Queued status (you must also send Authorization header)

  "error": { ^[*] 
If your conversion was not queued you may receive more details in this field

    "code"
    "message"
    "details": [{"code","message","details"}, ...]
  }
}

Submit simple conversion

Simplest PDF conversion job would contain only htmlTemplateUrl or htmlTemplate. In this example we are also using optional element data for pairing HTML with JSON data:

Method: /API/v1/conversion/add-to-queue

{
  "htmlOptions": {
    "htmlTemplateUrl": "https://html2pdf.appbeat.io/examples/SimpleInvoiceTemplate.html",
    "data": {
      "invoiceNumber": "123",
      "customerName": "John Doe",
      "summary": "<u>example</u>",
      "totalAmount": "456.78"
    }
  }
}

Response example:

{
  "status": "ConversionQueued",
  "jobId": "5bb5540a-3c2a-42ae-a730-1d9d5a531b5b",
  "statusUrl": "https://html2pdf.appbeat.io/API/v1/conversion/status/5bb5540a-3c2a-42ae-a730-1d9d5a531b5b/A6HBzEh0nbXR1gB8PJW7qaa_F9yOCcuIN_UGFcwlViQ",
  "cancelUrl": "https://html2pdf.appbeat.io/API/v1/conversion/cancel/5bb5540a-3c2a-42ae-a730-1d9d5a531b5b/A6HBzEh0nbXR1gB8PJW7qaa_F9yOCcuIN_UGFcwlViQ"
}

Conversion status

In /API/v1/conversion/add-to-queue response you will receive statusUrl value which targets /API/v1/conversion/status API. You can use this endpoint to check current PDF conversion status:

$ curl -H Authorization: AppBeat TestKeyId:v1,1580633761:4H3UzCkLgxk76jjCS6afhihNa6zR/E7qY9vyuPbbN8U= \
-H "Content-Type: application/json" -X GET \
https://html2pdf.appbeat.io/API/v1/conversion/status/5bb5540a-3c2a-42ae-a730-1d9d5a531b5b/7223f8a7-dbd8-cd08-be71-c992cbab410b-b016ced6-f31a-6da9-f2fa-dfbf8183468b

Response example for PDF conversion which is currently in progress:

{
  "conversionStatus": "Processing"
}

If you repeat same request after few moments and job was successfully finished, you should receive result similar to this:

{
  "conversionStatus": "Processed",
  "deliveryDetails": [
    {
      "status": "Success",
      "deliveryType": "S3",
      "details": {
        "awsRegion": "us-east-1",
        "awsBucketName": "html2pdf-example",
        "filename": "5bb5540a-3c2a-42ae-a730-1d9d5a531b5b.pdf",
        "downloadUrl": " https://html2pdf-example.s3.us-east-1.amazonaws.com/5bb5540a-3c2a-42ae-a730-1d9d5a531b5b.pdf"
      }
    }
  ]
}

Completed conversion & webhook notification

If you set deliveryOptions.webhookUrl in /API/v1/conversion/add-to-queue request we will send JSON payload to this URL when conversion is complete (we will use POST request method). JSON payload will have same structure as in /API/v1/conversion/status method.

Webhook JSON payload example for successful conversion:

{
  "conversionStatus": "Processed",
  "deliveryDetails": [
    {
      "status": "Success",
      "deliveryType": "S3",
      "details": {
        "awsRegion": "us-east-1",
        "awsBucketName": "html2pdf-example",
        "filename": "5bb5540a-3c2a-42ae-a730-1d9d5a531b5b.pdf",
        "downloadUrl": " https://html2pdf-example.s3.us-east-1.amazonaws.com/5bb5540a-3c2a-42ae-a730-1d9d5a531b5b.pdf"
      }
    }
  ]
}

Webhook JSON payload example for failed conversion:

{
  "conversionStatus": "Error",
  "error": {
    "code": "SystemError",
    "message": "Failed to download external HTML template"
  }
}

Sending raw HTML with embedded images and CSS styles

If you don't want to expose your HTML template publicly via htmlOptions.htmlTemplateUrl, you can send us your raw HTML via htmlOptions.htmlTemplate. You can also send embedded images and inline CSS as shown in example below:

Method: /API/v1/conversion/add-to-queue

{
  "payload": {
    "deliveryOptions": {
      "webhookUrl": "https://example.com/notification/webhook"
    },
    "htmlOptions": {
      "htmlTemplate": "
<!-- Embedded HTML template demo without external resources -->
<html>
<head></head>
<body>
   <div>
      <div class="invoice-header">Acme Corporation<br>Invoice No. {{invoiceNumber}}</div>
      <div>Bill to: <b>{{customerName}}</b></div>
      <div>Invoice summary: {{summary}}</div>
      <div>Total Amount: {{totalAmount}} USD</div>
      <div><img alt="Embedded PNG image example via data URI" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEUAJv//AACLe1F3AAAADklEQVQI12Pgh8IPEAgAEeAD/Xk4HBcAAAAASUVORK5CYII=" /></div>
   </div>
</body>
</html>",
      "data": {
        "invoiceNumber": "123",
        "customerName": "John Doe",
        "summary": "<u>example</u>",
        "totalAmount": "456.78"
      },
      "inlineCss": "
.invoice-header {
   background-color: #3284E0;
   color: #fff;
   padding: 0.5em;
}"
    },
    "pdfOptions": {
      "pageSize": {
        "predefinedPageSize": "A4"
      }
    }
  }
}

Create PDF with header & footer

If you would like to include header and/or footer on every PDF page you can use htmlHeaderTemplate and htmlFooterTemplate properties:

Method: /API/v1/conversion/add-to-queue

{
  "payload": {
    "deliveryOptions": {
      "webhookUrl": "https://example.com/notification/webhook",
      "deliveryTypes": [
        {
          "deliveryType": "S3"
        }
      ]
    },
    "htmlOptions": {
      "htmlTemplateUrl": "https://html2pdf.appbeat.io/examples/SimpleInvoiceTemplate.html",
      "data": {
        "invoiceNumber": "123",
        "customerName": "John Doe",
        "summary": "<u>example</u>",
        "totalAmount": "456.78"
      },
      "htmlHeaderTemplate": "My header text",
      "htmlFooterTemplate": "My footer text, page {{pageNumber}} of {{totalPages}}"
    },
    "pdfOptions": {
      "pageSize": {
        "predefinedPageSize": "A4"
      }
    }
  }
}

PDF delivery via email

If you don't want to bother with sending generated PDF documents via email you can provide us your SMTP server credentials and we will send email for you - as soon as PDF convrsion is complete. If we can't connect to your email server we will retry several times.

Method: /API/v1/conversion/add-to-queue

{
  "payload": {
    "deliveryOptions": {
      "webhookUrl": "https://example.com/notification/webhook",
      "deliveryTypes": [
        {
          "deliveryType": "Email",
          "options": {
            "subject": "Invoice {{invoiceNumber}} for {{customerName}}",
            "from": {
              "name": "From Name",
              "address": "from@example.com"
            },
            "to": {
              "name": "To Name",
              "address": "to@example.com"
            },
            "textBody": "Hi {{customerName}},\n\nWe are attaching you invoice Invoice-{{Html2Pdf_JobId}}.pdf\n\nKind regards,\nAcme Corporation",
            "htmlBody": "<p>Hi {{customerName}},</p><p>We are attaching you invoice Invoice-{{Html2Pdf_JobId}}.pdf</p><p>Kind regards,\nAcme Corporation</p>",
            "filenameTemplate": "Invoice-{{Html2Pdf_JobId}}.pdf",
            "secureSocketOptions": "sslOnConnect",
            "smtpServer": "smtp.example.com",
            "smtpPort": 465,
            "username": "YourSmtpUsername",
            "password": "YourSmtpPassword"
          }
        }
      ]
    },
    "htmlOptions": {
      "htmlTemplateUrl": "https://html2pdf.appbeat.io/examples/SimpleInvoiceTemplate.html",
      "data": {
        "invoiceNumber": "123",
        "customerName": "John Doe",
        "summary": "<u>example</u>",
        "totalAmount": "456.78"
      }
    },
    "pdfOptions": {
      "pageSize": {
        "predefinedPageSize": "A4"
      }
    }
  }
}

PDF delivery to your own AWS S3 bucket

If you want to store converted PDF documents in your AWS S3 bucket you will have to provide us your AWS S3 credentials as shown below:

awsCannedACL can have following values: BucketOwnerRead, AuthenticatedRead or PublicRead

For awsRegion values please use region codes found on following link: AWS Service Endpoints

Method: /API/v1/conversion/add-to-queue

{
  "payload": {
    "deliveryOptions": {
      "webhookUrl": "https://example.com/notification/webhook",
      "deliveryTypes": [
        {
          "deliveryType": "S3",
          "options": {
            "awsAccessKeyId": "YourAwsAccessKeyId",
            "awsSecretAccessKey": "YourAwsSecretAccessKey",
            "awsRegion": "us-east-1",
            "awsBucket": "YourAwsBucket",
            "awsCannedACL": "BucketOwnerRead"
          }
        }
      ]
    },
    "htmlOptions": {
      "htmlTemplateUrl": "https://html2pdf.appbeat.io/examples/SimpleInvoiceTemplate.html",
      "data": {
        "invoiceNumber": "123",
        "customerName": "John Doe",
        "summary": "<u>example</u>",
        "totalAmount": "456.78"
      }
    },
    "pdfOptions": {
      "pageSize": {
        "predefinedPageSize": "A4"
      }
    }
  }
}

Create PDF only if all external resources are downloaded

When we load your HTML template in Chrome engine, external resources may be requested, for example: images, CSS styles, JavaScript, ...

Some of those resources may fail to load due to connectivity issues or external server may be temporary unavailable. This may produce PDF with missing images or wrong CSS styling. To prevent this from happening you can set doNotContinueOnResourceDownloadError to true. If this flag is set and we can't download all external resources, PDF generation will fail and we will not continue with delivery.

Method: /API/v1/conversion/add-to-queue

{
  "payload": {
    "deliveryOptions": {
      "webhookUrl": "https://example.com/notification/webhook",
      "deliveryTypes": [
        {
          "deliveryType": "S3"
        }
      ]
    },
    "htmlOptions": {
      "htmlTemplateUrl": "https://html2pdf.appbeat.io/examples/SimpleInvoiceTemplate.html",
      "doNotContinueOnResourceDownloadError": true,
      "data": {
        "invoiceNumber": "123",
        "customerName": "John Doe",
        "summary": "<u>example</u>",
        "totalAmount": "456.78"
      }
    },
    "pdfOptions": {
      "pageSize": {
        "predefinedPageSize": "A4"
      }
    }
  }
}

Encrypted payload

In addition to TLS transport security you can protect your payload with AES-256 encryption before sending request over network. This is optional (advanced) functionality for maximum security.

First you have to generate your AES-256 encryption key by calling /API/v1/management/create-crypto-key method as described in "Create crypto key" example.

Once you successfully created crypto key, you can call /API/v1/conversion/add-to-queue method with encrypted payload by using your newly created key as following:

Method: /API/v1/conversion/add-to-queue

{
  "encryptedPayload": "Base64( AES-256-Encrypt( YourPrivateAesKey, UTF8-Encoding-Of( YourJsonPayload ) ) )",
  "encryptedPayloadKeyDetails": {
    "keyId": "0915ecf0-bd91-46a1-be0a-9a7923dda3aa",
    "sharedKeyBase64": "m9YwSSvrwUMCfwSvtDqO7plcWPRVuJkLnSEbEQvyI1c="
  }
}

Where:

YourPrivateAesKey = Base64-Decode( privateKeyBase64 );
keyId and sharedKeyBase64 are your actual values from latest /API/v1/management/create-crypto-key method response
YourJsonPayload has same JSON structure as with unencrypted HTML to PDF conversion, for example:

{
  "payload": {
    "deliveryOptions": {
      "webhookUrl": "https://example.com/notification/webhook",
      "deliveryTypes": [
        {
          "deliveryType": "S3"
        }
      ]
    },
    "htmlOptions": {
      "htmlTemplateUrl": "https://html2pdf.appbeat.io/examples/SimpleInvoiceTemplate.html",
      "data": {
        "invoiceNumber": "123",
        "customerName": "John Doe",
        "summary": "<u>example</u>",
        "totalAmount": "456.78"
      }
    },
    "pdfOptions": {
      "pageSize": {
        "predefinedPageSize": "A4"
      }
    }
  }
}

PDF delivery options

We can currently deliver your PDF files by following channels:

Delivery type	Storage owner	Data retention	Comment
AWS S3	AppBeat	approx. 1 day	PDF is automatically deleted after retention period
AWS S3	Customer	N/A, managed by customer	Applicable if customer provides their own AWS credentials, bucket & region. Please see example for more details.
Email	Other	N/A, managed by administrator of destination email server	PDF can be sent as attachment to different email receivers. Please see example for more details.

Delivery type	Storage owner	Data retention
AWS S3	AppBeat	approx. 1 day
PDF is automatically deleted after retention period
AWS S3	Customer	N/A, managed by customer
Applicable if customer provides their own AWS credentials, bucket & region. Please see example for more details.
Email	Other	N/A, managed by administrator of destination email server
PDF can be sent as attachment to different email receivers. Please see example for more details.

In future versions we may add additional delivery options, for example SFTP, Azure Storage, Amazon Simple Queue Service, various databases, ... Please let us know if you are interested!

Security recommendation: When sending sensitive data, for example customer provided AWS S3 credentials, email credentials, etc., we recommend application payload protection with encryption key.

Synchronous PDF conversion

This API allows you to submit HTML to PDF conversion job, your client waits for result and downloads converted PDF.

Note: For this API your client must support 3xx redirections.

Supported request encodings:

Form encoded request for POST method /API/v1/conversion/download
application/json in request body for POST method /API/v1/conversion/download-from-json

Supported response encodings:

/API/v1/conversion/download and /API/v1/conversion/download-from-json can redirect you to PDF download location which returns application/pdf
in all other cases, if response body is returned, you should get application/json

JSON request structure for /API/v1/conversion/download-from-json

{
  "deduplicationId" ^[*] 
Optional external ID to prevent multiple conversion calls for same document during last 24 hours. Max length: 36 characters.

  "htmlOptions": {
    "htmlTemplate" ^[*] 
HTML document which is converted to PDF. For example:

<html>
   <head>
      <!-- CSS styles, ... -->
   </head>
   <body>
      <!-- formatted content -->
   </body>
</html>

Note: if you use this field you can't use htmlTemplateUrl

    "htmlTemplateUrl" ^[*] 
External URL of HTML template which is converted to PDF. For example: https://example.com/Template.html

Note: if you use this field you can't use htmlTemplate

    "doNotContinueOnResourceDownloadError" ^[*] 
If there are 4xx or 5xx errors while loading template resources (external images, external scripts, external styles) do not continue with PDF covnersion because result may not look 'nice' (missing images, etc).
Possible values: null, true, false
Default value: false

    "data" ^[*] 
Optional collection of name/value pairs which are paired with your HTML template.

    "mediaType" ^[*] 
Selects CSS style for targeting media type.
Possible values: null, "Default", "Print", "Screen"
Default value: "Screen"

    "inlineCss" ^[*] 
Additional CSS style for your HTML document (optional). For example:

.myCssStyle {
   background-color: yellow;
   font-size: large;
}

#myElement {
   font-weight: bold;
}

    "renderBackground" ^[*] 
Should HTML background be included when creating PDF?
Possible values: null, true, false
Default value: true

    "scale" ^[*] 
Scaling factor between 0.2 and 4.0
Default value: 1.0

    "htmlHeaderTemplate" ^[*] 
Optional HTML template which is inserted into page header.
Possible variables: {{pageNumber}}, {{totalPages}}
Example: This is <b>header</b> text, page {{pageNumber}} of {{totalPages}}

    "htmlFooterTemplate" ^[*] 
Optional HTML template which is inserted into page footer.
Possible variables: {{pageNumber}}, {{totalPages}}
Example: This is <b>footer</b> text, page {{pageNumber}} of {{totalPages}}

  },
  "pdfOptions": {
    "pageOrientation" ^[*] 
Possible values: null, "Default", "Landscape", "Portrait"
Default value: "Portrait"

    "pageSize": { ^[*] 
You can set predefinedPageSize or custom width and height where you can use following unit values: "Centimeters", "Inches", "Millimeters"
Default value: {"pageSize":{"predefinedPageSize":"A4"}}

      "width": {
        "value"
        "unit"
      },
      "height": {
        "value"
        "unit"
      },
      "predefinedPageSize" ^[*] 
Possible predefinedPageSize values: null, "A0", "A1", "A2", "A3", "A4", "A5", "Default", "Ledger", "Legal", "Letter", "Tabloid"
Default value if width and height are not set: "A4"
Which is equivalent to: {"pageSize":{"width":{"value":210,"unit":"Millimeters"},"height":{"value":297,"unit":"Millimeters"}}}

    },
    "margin": { ^[*] 
Space between the text and the edge of your PDF document.
Possible unit values: "Centimeters", "Inches", "Millimeters"
Default value: {"margin":{"top":{"value":25.4,"unit":"Millimeters"},"bottom":{"value":25.4,"unit":"Millimeters"},"left":{"value":25.4,"unit":"Millimeters"},"right":{"value":25.4,"unit":"Millimeters"}}}

      "top": {
        "value"
        "unit"
      },
      "bottom": {
        "value"
        "unit"
      },
      "left": {
        "value"
        "unit"
      },
      "right": {
        "value"
        "unit"
      }
    }
  }
}

Form encoded request structure for /API/v1/conversion/download

deduplicationId=""
htmlOptions.htmlTemplate=""
htmlOptions.htmlTemplateUrl=""
htmlOptions.doNotContinueOnResourceDownloadError=""
htmlOptions.data=""
htmlOptions.mediaType=""
htmlOptions.inlineCss=""
htmlOptions.renderBackground=""
htmlOptions.scale=""
htmlOptions.htmlHeaderTemplate=""
htmlOptions.htmlFooterTemplate=""
pdfOptions.pageOrientation=""
pdfOptions.pageSize.width.value=""
pdfOptions.pageSize.width.unit=""
pdfOptions.pageSize.height.value=""
pdfOptions.pageSize.height.unit=""
pdfOptions.pageSize.predefinedPageSize=""
pdfOptions.margin.top.value=""
pdfOptions.margin.top.unit=""
pdfOptions.margin.bottom.value=""
pdfOptions.margin.bottom.unit=""
pdfOptions.margin.left.value=""
pdfOptions.margin.left.unit=""
pdfOptions.margin.right.value=""
pdfOptions.margin.right.unit=""

Note: Form encoded fields are identical to /API/v1/conversion/download-from-json JSON structure. Server uses same logic for both methods.

Other request examples

Supported request encodings:

application/json in request body for POST methods

Supported response encodings:

if response body is returned, you should get application/json

Create crypto key

Method: /API/v1/management/create-crypto-key

{
  "cryptoAlgorithm": "Aes256"
}

Response example:

{
  "keyId": "0915ecf0-bd91-46a1-be0a-9a7923dda3aa",
  "cryptoAlgorithm": "Aes256",
  "privateKeyBase64": "TCPRMo2a5uTpmmDYEyRw8rpZN9utN9IAvwY7cChWPaQ=",
  "sharedKeyBase64": "m9YwSSvrwUMCfwSvtDqO7plcWPRVuJkLnSEbEQvyI1c=",
  "status": "Success"
}

You should securely store this response and you must not share privateKeyBase64 with anyone. privateKeyBase64 contains Base64 encoded AES 256 key.

Important: You will receive only one unique response for each /API/v1/management/create-crypto-key request. If you lose key details from this response we can not resend it because we don't store your full key details on our servers, only parts (keyId and part of your private key) which are not enough to reconstruct your full private key (privateKeyBase64).

API specification

Resources for v1:

interactive Swagger documentation
OpenAPI 3.0 swagger.json definition

Security & Privacy

Support for strong encryption: Data in transit is always encrypted with TLS. API request payload and PDF result can be encrypted by application with AES-256-bit encryption key for most sensitive conversions. Please see »Encrypted payload« example for more details.
Temporary working storage: Worker nodes use memory and local temporary storage during conversion. Once they deliver PDF result, memory is cleared and temporary storage is deleted.
PDF delivery credentials: We don't store your delivery credentials (for example your own AWS S3, email servers), we always use credentials from your request.
PDF delivery storage: If you choose to deliver your PDFs to our AWS S3 storage, documents will be available for you to download for approximately one day. After this period files will be automatically deleted by AWS S3: Object Lifecycle Management. Lifecycle policies for all other delivery methods are not under our control.
Possible to setup private worker node(s): For Advanced plans and higher we can provide dedicated private worker node(s) by provider and region of your choice (Amazon AWS, Microsoft Azure, Google Cloud Platform, ...). This option is available on yearly plans and for additional fee.

Have questions or suggestions?

We will be happy to receive your feedback or to answer your questions. You can contact us by using our contact form.

Convert your HTML to PDF

with simple REST API & Chrome rendering engine

Built by developers, for developers

API endpoints & authentication

Quick information

Asynchronous PDF conversion

Request structure

Response structure

Submit simple conversion

Conversion status

Completed conversion & webhook notification

Sending raw HTML with embedded images and CSS styles

Create PDF with header & footer

PDF delivery via email

PDF delivery to your own AWS S3 bucket

Create PDF only if all external resources are downloaded

Encrypted payload

PDF delivery options

Synchronous PDF conversion

JSON request structure for /API/v1/conversion/download-from-json

Form encoded request structure for /API/v1/conversion/download

Other request examples

Create crypto key

API specification

Security & Privacy

Have questions or suggestions?