Architecture

The interface is located at the address https://pdfmage.org/pdf-api/v1

API uses REST architecture. The parameters are sent using POST method in the request body in “key=value” format or in JSON. The format is determined on client side, by the providing the "Content-Type" header:

• For “key=value” parameters Content-Type should be: application/x-www-form-urlencoded
• For JSON parameters Content-Type should be: application/json

The system will normally respond with HTTP 200 status, sending a JSON response body which will have a "Success" parameter, and optional "Error" message and "Data":

Request authentication

Requests are authenticated based on the "X-Api-Key" HTTP header, which should contain your unique API key. API keys can be obtained after purchasing API access.

If the request does not have a header with authentication information, or the information sent in the request is incorrect, the system will return a HTTP 401 status – Unauthorized.

Test method

To check interaction with API you can call a test method at https://pdfmage.org/pdf-api/v1/sample without sending any parameters. The system will return a sample PDF download URL.

Sample request:

Sample response:

Generate PDF from HTML

To generate PDF from custom HTML, make a request to the following address: https://pdfmage.org/pdf-api/v1/process. These are the parameters you can use:

Parameter	Format	Required	Description
Html	String	Yes*	HTML markup that needs to be converted to PDF * Required if TargetUrl parameter is not specified
TargetUrl	String	Yes*	The URL at which HTML page is located (used to download scripts, styles, images and other files needed for HTML page to be displayed properly) * Required if Html parameter is not specified
PageWidth	Numeric	No	HTML viewer width in pixels (default is 1024)
PageOrientation	String	No	Determines PDF page orientation. Possible values are: Portrait Landscape Default value is Portrait.
SinglePage	Boolean	No	Determines whether to split PDF file into pages, or use single page regardless of HTML page size
CompressPdf	Boolean	No	Determines whether to compress images and other resources for reducing PDF size
HideImages	Boolean	No	Determines whether to hide images in PDF
DisableLinks	Boolean	No	Determines whether to disable clickable links in PDF
DisplayDateInFooter	Boolean	No	Determines whether to display creation date and time in PDF footer
PdfPassword	String	No	Set this to protect your PDF with a password
AllowPrinting	Boolean	No	Determines whether to allow printing of the resulting PDF
AllowCopying	Boolean	No	Determines whether to allow copying content from the resulting PDF
AllowEditing	Boolean	No	Determines whether to allow editing of the resulting PDF
PaperSize	String	No	Customize paper size of the resulting PDF. Possible values are: A4 - for 8.25 x 11.75 in size Letter - for 8.5 x 11 in size Legal - for 8.5 x 14 in size Ledger - for 11 X 17 in size A0 - for 33.125 x 46.75 in size A1 - for 23.375 x 33.125 in size A2 - for 16.5 x 23.375 in size A3 - for 11.75 x 16.5 in size Default value is A4.
RightMargin LeftMargin TopMargin BottomMargin	Numeric	No	Set these values to customize PDF page margins. Note: margins are measured in points (1 point = 1/72 inch)

Sample request:

Sample response:

Check your API key

To check your API key, make a request to the following address: https://pdfmage.org/pdf-api/v1/check-key without sending any parameters. You should pass your key in request headers, like for all other methods.

Sample request:

Sample response:

Rate limiting

Our API is currently rate limited. You may only perform requests from a single IP address every 5 seconds. If you attempt to make more frequent requests, the system will return a HTTP 409 status – Conflict.