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 /watermark/pdf POST /protect/pdf POST /compress/pdf POST /envelope POST /envelope/:id/send POST /upload	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	40 concurrent requests	10 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) and cannot be increased. 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

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

viewport object

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

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

Create Envelope

The Create Envelope endpoint creates a new envelope from one or more existing source documents.

Each document must reference a previously created document by its sourceDocumentId and include one or more recipients.

You can also attach optional metadata to the envelope for your own tracking and internal reference.

This endpoint creates the envelope in the created status. After calling this endpoint, you should use the POST /envelope/:id/send endpoint to send an email to the recipient with a link to the signing UI, where they can sign the document.

See the Getting Started guide for a complete example.

Endpoint

POSThttps://api.pdfgate.com/envelope

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Request body fields

documents array required

requesterName string required

Name of the user or system creating the envelope.

metadata object

Available responses

Send Envelope

The Send Envelope endpoint sends an email to each recipient in the envelope with a secure link to access the signing UI and sign the document. The link remains valid for 30 days, after which it expires and can no longer be used. To ensure secure access, recipients must complete OTP (one-time password) verification before accessing the signing experience.

Endpoint

POSThttps://api.pdfgate.com/envelope/:id/send

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Request path parameters

id string required

The envelope ID.

Available responses

Get Envelope

The Get Envelope endpoint retrieves the current state of an envelope by its ID.

You can use this endpoint to track the envelope status, inspect document-level progress, and view recipient statuses.

Endpoint

GEThttps://api.pdfgate.com/envelope/:id

Examples

CURL

NODE.JS

PYTHON

PHP

JAVA

RUBY

Request path parameters

id string required

The envelope ID.

Available responses