API Documentation

The PDFGate API provides a set of HTTP endpoints for working with PDF documents, with a focus on digital signatures. You can sign documents and manage document workflows, along with generating PDFs from HTML or URLs and processing existing files.

All requests are authenticated using an API key and return JSON responses using standard HTTP status codes.

PDFGate offers a sandbox environment for testing your integration without affecting production data. The environment is determined by the request URL, and your API key must match the selected environment.

Each request operates on a single document or resource.

Authentication

All API requests must be authenticated using an API key. Authentication is handled via the Authorization header in your HTTP requests.

To get started, log in to your PDFGate account and create an API key from the Settings page in the dashboard. Ensure the key is active before using it in your code.

Include the API key in your request headers like this:

PDFGate supports two types of API keys:

Production: live_xxxxxxxxxxxxxxx
Sandbox: test_xxxxxxxxxxxxxxx

Use sandbox keys for testing purposes and production keys in your live environment.

Rate limits

The PDFGate API uses different rate limits for each account type in the production environment. In the sandbox environment, the rate limits are the same for all account types.

Endpoint	Production	Sandbox
POST /v1/generate/pdf POST /forms/flatten POST /forms/extract-data POST /forms/fields POST /watermark/pdf POST /protect/pdf POST /compress/pdf POST /envelope POST /envelope/:id/send POST /upload POST /webhook	Per account type requests: Personal: 3 Starter: 3 Basic: 5 Professional: 10 Professional Plus: 20	Per account type requests: Personal: 2 Starter: 2 Basic: 2 Professional: 2 Professional Plus: 2
GET /document/:id DELETE /document/:id GET /file/:id GET /envelope/:id GET /webhook/:id DELETE /webhook/:id	Per account type requests: Personal: 40 Starter: 50 Basic: 100 Professional: 150 Professional Plus: 200	30 concurrent requests

Errors

Code	Error
400	Bad request
401	Unauthorized
404	Not found
422	Unprocessable entity
429	Too many requests
500	Internal server error

Generate PDF

The Generate PDF endpoint converts HTML content into a PDF document. You can provide the content either as a publicly accessible URL or as raw HTML in the request body.

By default, the endpoint returns the generated PDF as a binary file. If you prefer a JSON response, you can include the jsonResponse field in your request.

Endpoint

POSThttps://api.pdfgate.com/v1/generate/pdf

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Request body fields

html string required if url field is not provided

url string required if html field is not provided

jsonResponse boolean

Default: false

Returns JSON response instead of file stream.

preSignedUrlExpiresIn number

Minimum: 60 seconds

Maximum: 86400 seconds (24 hours)

Use this to control temporary authorized access to files. After this duration, the URL automatically expires and can no longer be used to download the PDF. The value must be provided in seconds.

If you need to generate a new pre-signed URL for an existing document, use the Get Document endpoint.

pageSizeType string

Default: ledger

Acceptable values

a0a1a2a3a4a5a6ledgertabloidlegalletter

width number

Custom PDF file width in pixels (px). It needs to be defined with the height field.

height number

Custom PDF file height in pixels (px). It needs to be defined with the width field.

orientation string

Default: portrait

Acceptable values

portraitlandscape

header string

footer string

margin object

timeout number

Default: 900000 - (15 minutes)

Maximum wait time (in milliseconds) to render the HTML content.
The default and maximum value is 900000 ms (15 minutes).
Use this parameter to stop the rendering process earlier if needed.

javascript string

css string

emulateMediaType string

Sets the CSS media type of the document.

Acceptable values

screenprint

waitForSelector string

Waits for specific CSS selector to be loaded. It will timeout in 30 seconds.

clickSelector string

Waits and then clicks a specific CSS selector.

clickSelectorChainSetup object

Provides advanced control for handling cookie banners, consent dialogs, pop-ups, and multi-step UI interactions before capturing the PDF.

When it is defined, the clickSelector field is ignored.

Value example

waitForNetworkIdle boolean

Waits until there are no more network connections in the document.

delay number

Adds a delay in milliseconds before processing the HTML content into a PDF. This can be useful when asynchronous content needs extra time to render. The maximum value you can set is 20 seconds (20000 in ms).

loadImages boolean

Waits for all images to finish loading before generating the PDF.

scale number

Default: 1

Sets the page scale factor when generating the PDF. Accepts values between 0.1 and 2.

pageRanges string

Defines the page range to include in the PDF. Accepts formats like "1-5" or "1,3,5". If not specified, all pages are included.

printBackground boolean

Default: true

Includes background graphics in the PDF when set to true. If false, backgrounds are omitted and only main content is rendered.

userAgent string

Set your own user agent string to control how the page content is served.

httpHeaders object

Sets custom HTTP headers.

authentication object

Page authentication allows you to render pages that are protected by HTTP authentication.

It is supported only when rendering a URL and cannot be used with HTML content.

See the authenticated pages guide for a full example.

viewport object

Page viewport allows you to control the visible area of the page before it is rendered.

enableFormFields boolean

If enabled, the generated PDF will include interactive form fields (e.g., text inputs, checkboxes) that users can fill out directly in PDF viewers.

Supported HTML tags

input[type='text'] input[type='checkbox'] textarea select input[type='email'] input[type='number'] input[type='datetime-local'] input[type='date'] input[type='time'] input[type='radio']

For digital signature field we support the following custom HTML tag

<pdfgate-signature-field />

Detailed documentation

Generated PDF example

metadata object

Sets custom data to your document record.

Available responses

Flatten PDF

The Flatten PDF endpoint converts an interactive PDF (with fillable form fields or annotations) into a static, non-editable version.

You can flatten a document in two ways:

Upload a PDF file with form data directly, or
Provide a documentId referencing an existing file already stored in our database.

If a documentId is provided, the API will always create a new flattened file in the database, rather than overwriting the existing one.

In this case, the response includes a derivedFrom parameter (when jsonResponse is set to true), it indicates the original document ID from which the flattened file was created.

Endpoint

POSThttps://api.pdfgate.com/forms/flatten

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Request body fields

file file required if documentId is not provided

File type: .pdf

The PDF file to be processed. Used when uploading a new file directly.

documentId string required if uploaded file is not provided

The ID of an already uploaded file stored on our server.

jsonResponse boolean

Default: false

Returns JSON response instead of file stream.

preSignedUrlExpiresIn number

Minimum: 60 seconds

Maximum: 86400 seconds (24 hours)

Use this to control temporary authorized access to files. After this duration, the URL automatically expires and can no longer be used to download the PDF. The value must be provided in seconds.

If you need to generate a new pre-signed URL for an existing document, use the Get Document endpoint.

metadata object

Sets custom data to your document record.

Available responses

Extract PDF Form Data

The Extract PDF Form Data endpoint lets you read data from a fillable PDF. It extracts all form fields in the document along with their current values and returns them as a JSON object.

You can either upload a new PDF file directly or provide the documentId of an existing file stored on the server.

Endpoint

POSThttps://api.pdfgate.com/forms/extract-data

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Request body fields

file file required if documentId is not provided

File type: .pdf

The PDF file to be processed. Used when uploading a new file directly.

documentId string required if uploaded file is not provided

The ID of an already uploaded file stored on our server.

Available responses

Add Form Fields to PDF

This endpoint adds interactive form fields to any existing PDF using placeholder tags.
Tags are written as plain text, so you can add them in any PDF editor or document editor that can export files as PDFs. They look like regular text. For example, the tag {signature;n:sign_here;r:signer}, when processed, will be replaced in the PDF with a digital signature field named "sign_here" and assigned to the role "signer".

Our API automatically removes placeholder tags from the PDF after processing. However, in some cases, the original tag text may remain. To ensure the tags are not visible, we recommend setting their text color to match the background color.

Note: Tags must be written on a single line. If they are split across multiple lines, they will not be detected.

Tag syntax

Each tag starts with the field type. Additional properties are optional and use a key:value format separated by semicolons.

Key	Description	Required	Applies to
`type`	The field type. Must always be defined first. Supported field types are listed below.	Yes	All
`n:`	The field name. Radio buttons with the same name are grouped together. The name also links the field to a `fieldOverrides` entry.	No	All
`r:`	Associates the field with a signing role. Only users assigned to that role can interact with the field.	No	All
`h:`	The field height in points. By default, the height is automatically detected from the placeholder tag, but you can override it using this tag or through the `fieldOverrides` option if needed.	No	All
`w:`	The field width in points. By default, the width is automatically detected from the placeholder tag, but you can override it using this tag or through the `fieldOverrides` option if needed.	No	All
`fs:`	Sets the field font size. By default, the font size is automatically calculated based on the field height, but you can override it using this tag if needed.	No	text, number, textarea, date, time, datetime, select
`o:`	A comma-separated list of options for the select field.	No	select only
`c:`	Specifies the value represented by this radio button within the group.	No	radio only

Example tags:

Tags are case-sensitive. Keys and field types must be written exactly as shown below.

Supported field types

Type	Description
`text`	Creates a standard text input field.
`number`	A text field that only accepts numbers.
`textarea`	Creates a text input field that supports multiple lines.
`date`	Stored as a text field in the PDF. In our signing UI is presented as a date picker.
`time`	Stored as a text field in the PDF. In our signing UI is presented as a time picker.
`datetime`	Stored as a text field in the PDF. In our signing UI is presented as a date and time picker. You can automatically populate this field when the document is signed by setting `autoFill` in `fieldOverrides`.
`checkbox`	Creates a standard checkbox field.
`radio`	Creates a radio button field. Radio buttons that share the same name behave as a group.
`select`	Creates a dropdown field. Options can be provided inline using the tag `o:` or through `fieldOverrides`.
`signature`	Defines a field where a recipient can provide their signature. It is primarily used with the digital signatures feature to collect signatures in the signing UI.

Endpoint

POSThttps://api.pdfgate.com/forms/fields

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Request body fields

file file required if documentId is not provided

File type: .pdf

The PDF file to process. It should contain placeholder tags.

documentId string required if file is not provided

The ID of a document that was previously uploaded to PDFGate.

fieldOverrides object

Lets you set or override field properties at request time, keyed by field name. This is useful when values like options or dimensions are dynamic and you cannot hardcode them into the tag itself.

jsonResponse boolean

Default: false

Returns JSON response instead of file stream.

preSignedUrlExpiresIn number

Minimum: 60 seconds

Maximum: 86400 seconds (24 hours)

How long the pre-signed URL stays valid, in seconds. If you leave this out, no URL is generated.

metadata object

Any custom data you want to store alongside the document.

Available responses

Watermark PDF

The Watermark PDF endpoint adds a watermark to an existing PDF document. You can apply either a text watermark or an image watermark, depending on your needs.

Endpoint

POSThttps://api.pdfgate.com/watermark/pdf

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Request body fields

file file required if documentId is not provided

File type: .pdf

The source PDF file to watermark. Either file or documentId must be provided.

documentId string required if uploaded file is not provided

The unique identifier of an existing uploaded document. Use this when watermarking a file that's already stored on our database.

watermark file

File types: .png .jpeg .jpg

The image to be used as a watermark. Provide this field if you want an image watermark instead of text.

fontFile file

File types: .ttf .otf

A custom font file for text watermarks.

type string required

Acceptable values

textimage

Use text for a text watermark and image for an image watermark.

text string required if type is set to text

The text you want to appear as the watermark.

font string

Default: helvetica

Acceptable values

times-romantimes-boldtimes-italictimes-bolditalichelveticahelvetica-boldhelvetica-obliquehelvetica-boldobliquecouriercourier-boldcourier-obliquecourier-boldoblique

The font name to use for the text watermark. Must be one of the standard PDF fonts. If the fontFile is provided, this parameter will be ignored.

fontSize number

Default: 30

The size of the watermark text, in points.

fontColor string

The color of the text watermark. Accepts a hex color (e.g., #FF0000) or an RGB value (e.g., rgb(255,0,0)).

opacity number

Default: 1

Sets the transparency of the watermark, from 0 (fully transparent) to 1 (fully opaque). It applies to both text and image watermarks.

xPosition number

The horizontal position (in points) where the image or text watermark will be placed. If not provided a centered position will be applied.

yPosition number

The vertical position (in points) where the image or text watermark will be placed. If not provided, a centered position will be applied.

imageWidth number

The width (in points) to resize the watermark image to. If not provided, the image keeps its original width.

imageHeight number

The height (in points) to resize the watermark image to. If not provided, the image keeps its original height.

rotate number

Rotates the watermark by the specified angle in degrees (0-360). Useful for diagonal watermarks.

jsonResponse boolean

Default: false

Returns JSON response instead of file stream.

preSignedUrlExpiresIn number

Minimum: 60 seconds

Maximum: 86400 seconds (24 hours)

Use this to control temporary authorized access to files. After this duration, the URL automatically expires and can no longer be used to download the PDF. The value must be provided in seconds.

If you need to generate a new pre-signed URL for an existing document, use the Get Document endpoint.

metadata object

Sets custom data to your document record.

Available responses

Protect PDF

The Protect PDF endpoint secures a PDF document by applying password protection and permission restrictions.

You can encrypt the PDF using AES-128 or AES-256, set user and owner passwords, and control which actions are allowed, such as printing, copying, or editing.

Endpoint

POSThttps://api.pdfgate.com/protect/pdf

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Request body fields

file file required if documentId is not provided

File type: .pdf

The PDF file to be processed. Used when uploading a new file directly.

documentId string required if uploaded file is not provided

The ID of an already uploaded file stored on our server.

algorithm string

Default: AES256

Acceptable values

AES256AES128

Specifies the encryption algorithm. AES256 offers the highest security, while AES128 ensures better compatibility with older PDF readers.

userPassword string

Password required to open the PDF. If not provided, the document will be accessible without a password unless restrictions depend on the owner password.

ownerPassword string

Password that grants full control over the PDF, including the ability to change permissions or remove restrictions. Must not be empty if AES256 is used and a userPassword is defined.

disablePrint boolean

When true, prevents the PDF from being printed.

disableCopy boolean

When true, disables copying or text/image extraction from the document.

disableEditing boolean

When true, prevents modifications to the document (e.g., form editing or annotation changes).

encryptMetadata boolean

Default: false

Determines whether the document metadata (title, author, keywords, etc.) should be encrypted. If set to false, metadata remains visible without decryption.

jsonResponse boolean

Default: false

Returns JSON response instead of file stream.

preSignedUrlExpiresIn number

Minimum: 60 seconds

Maximum: 86400 seconds (24 hours)

Use this to control temporary authorized access to files. After this duration, the URL automatically expires and can no longer be used to download the PDF. The value must be provided in seconds.

If you need to generate a new pre-signed URL for an existing document, use the Get Document endpoint.

metadata object

Sets custom data to your document record.

Available responses

Compress PDF

The Compress PDF endpoint reduces the file size of a PDF without changing its visual appearance. You can also enable linearization so the first page loads faster when the PDF is opened over a network.

Note: In the sandbox environment, the compression result may be limited because our watermark image is automatically added to the document. As a result, the file size will be increased. We recommend testing this endpoint in the production environment.

Endpoint

POSThttps://api.pdfgate.com/compress/pdf

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Request body fields

file file required if documentId is not provided

File type: .pdf

The PDF file to be processed. Used when uploading a new file directly.

documentId string required if uploaded file is not provided

The ID of an already uploaded file stored on our server.

linearize boolean

Default: false

When true, re-arranges the PDF for Fast Web View so the first page can render before the full file downloads.

jsonResponse boolean

Default: false

Returns JSON response instead of file stream.

preSignedUrlExpiresIn number

Minimum: 60 seconds

Maximum: 86400 seconds (24 hours)

Use this to control temporary authorized access to files. After this duration, the URL automatically expires and can no longer be used to download the PDF. The value must be provided in seconds.

If you need to generate a new pre-signed URL for an existing document, use the Get Document endpoint.

metadata object

Sets custom data to your document record.

Available responses

Get document

Retrieves a generated document object containing metadata and file details.

Endpoint

GEThttps://api.pdfgate.com/document/{documentId}

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Request query fields

preSignedUrlExpiresIn number

Minimum: 60 seconds

Maximum: 86400 seconds (24 hours)

Use this to receive a temporary authorized URL for an existing file. After this duration, the URL automatically expires and can no longer be used to download the PDF. The value must be provided in seconds.

Response

Delete document

Deleting a document performs a soft delete to preserve internal records and maintain audit integrity.

When a document is deleted:

The generated document file is permanently removed from storage.
Any user-provided data, such as metadata, is anonymized.
The document record remains in the system for internal reference and auditing, but the document is no longer accessible or usable.

Note: Documents used as a source in an envelope with in_progress status cannot be deleted. A document can only be deleted once all associated envelopes are in created, completed, or expired status.

Endpoint

DELETEhttps://api.pdfgate.com/document/{documentId}

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Response

Get file

Retrieves a raw PDF file previously generated.

Note: To access a generated file, you must enable file storage in your PDFGate dashboard under Settings → Storage. Files are retained only for the configured storage duration. By default, file storage is disabled.

Endpoint

GEThttps://api.pdfgate.com/file/{documentId}

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Response

Upload file

Upload a PDF document. The document can be provided either as a file upload or by specifying a publicly accessible URL where the PDF is hosted.

Endpoint

POSThttps://api.pdfgate.com/upload

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Request body fields

file file required if url is not provided

File type: .pdf

Maximum size: 500 mb

The PDF file to be uploaded.

url string required if file is not provided

Use this parameter if you want to upload a PDF file accessible in a public URL.

preSignedUrlExpiresIn number

Minimum: 60 seconds

Maximum: 86400 seconds (24 hours)

Use this to control temporary authorized access to files. After this duration, the URL automatically expires and can no longer be used to download the PDF. The value must be provided in seconds.

If you need to generate a new pre-signed URL for an existing document, use the Get Document endpoint.

metadata object

Sets custom data to your document record.

Available responses