pdfRest Cloud API Reference Guide REST API Tools for simple PDF processing with GET and POST HTTP requests Getting Started
Welcome to the pdfRest Cloud API Reference Guide! Below you will find all the information you will need to get started using the pdfRest API Tools with your dedicated API Key. If you don't have a key yet, generate one for free at pdfrest.com/getstarted
This guide is organized by API endpoints, which express the output file types that can be generated from input files supplied with requests. For example, to convert a JPG file to a PDF, you would send the JPG file to the /pdf endpoint.
Additional Resources
API Lab - an intuitive interface to learn the tools and parameters, build code automatically, send API calls directly from the website, and download output files
GitHub Repository - functional code examples available for several popular languages
Summary Poll for the status of a request by ID. Request IDs can be found in the JSON response of POST requests sent to any pdfRest endpoint. To enable API Polling, include the following header parameter with the POST request:
Request-Type: requestId
Once a requestId is returned, it can be used with the /request-status endpoint to poll for the original POST request's status.
Examples
Required Headers
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Path Parameters
Name
Description
Default
Required
requestId
Alphanumeric ID (UUID) of the request to poll for its status
Accepts: Any valid requestId returned by a POST request
{
"error": "requestID not found. Please check that the Api-Key and requestId are correct. If this persists, please refer the issue to https://pdfrest.com/support." }
POST /pdf-info
Summary
Return detailed information about a PDF document and its contents to assess the current state of the file and drive conditional processing.
NOTE: Some PDF conditions can prevent all queries from completing. For example, if the document is password-protected, corrupted, or not actually a PDF, all queries will not be able to be completed. The output response will always include an "allQueriesProcessed" field with a true or false value. When this is false, an additional "warning" field will also be included in the output response with a human-readable string explaining why all queries could not be processed.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
queries
Comma separated list of information to request about the input PDF file and its contents.
Accepts:
tagged - Checks for presence of structure tags in the input document. Returns true or false
image_only - Checks if the document is 'image only' meaning that it will only feature a series of embedded graphical image files, one per page and does not have any text or other features common to PDF documents, except for some metadata. Returns true or false
title - The title of the PDF as listed in the metadata. Returns a string which may be empty if the document does not have a title
subject - The subject of the PDF as listed in the metadata. Returns a string which may be empty if the document does not have a subject
author - The author of the PDF as listed in the metadata. Returns a string which may be empty if the document does not have an author
producer - The producer of the PDF as listed in the metadata. Returns a string which may be empty if the document does not have a producer
creator - The creator of the PDF as listed in the metadata. Returns a string which may be empty if the document does not have a creator
creation_date - The creation date of the PDF as listed in the metadata. Returns a string which may be empty if the document does not have a creation date
modified_date - The most recent modification date of the PDF as listed in the metadata. Returns a string which may be empty if the document does not have a modification date
keywords - The keywords of the PDF as listed in the metadata. Returns a string which may be empty if the document does not have keywords
doc_language - The language that the file claims to be written in. Returns a string
page_count - The number of pages in the PDF document. Returns an integer
contains_annotations - Checks whether the document contains annotations, such as notes, highlighted text, file attachments, crossed out text, and text callout boxes. Returns true or false
contains_signature - Checks if the document contains any digital signatures. Returns true or false
pdf_version - Retrieves the version of the PDF standard that the document was created with. Returns a string of the form X.Y.Z where X, Y, and Z are the major, minor, and extension versions respectively
file_size - Retrieves the size of the input file in bytes. Returns an integer
filename - The name of the input file. Returns a string
restrict_permissions_set - Checks whether the document has restrict permissions set to prevent printing, copying, signing etc. Returns true or false
contains_xfa - Checks whether the document contains XFA forms. Returns true or false
contains_acroforms - Checks whether the document contains Acroforms. Returns true or false
contains_javascript - Checks whether the document contains javascript. Returns true or false
contains_transparency - Checks whether the document contains transparent objects. Returns true or false
contains_embedded_file - Checks whether the document contains one or more embedded files. Returns true or false
uses_embedded_fonts - Checks whether the document contains fully embedded fonts. Returns true or false
uses_nonembedded_fonts - Checks whether the document contains non-embedded fonts. Returns true or false
pdfa - Checks whether the document conforms to a PDF/A standard. Returns true or false
pdfua_claim - Checks whether the document claims to conform to a PDF/UA standard. Returns true or false
pdfe_claim - Checks whether the document claims to conform to a PDF/E standard. Returns true or false
pdfx_claim - Checks whether the document claims to conform to a PDF/X standard. Returns true or false
requires_password_to_open - Checks whether the document requires a password to open. Returns true or false. *Note* A document requiring a password cannot be opened by this route and will not be able to return much other information
{
"error": "This route will only accept a File or an ID, not both." }
401
Unauthorized
{
"error": "An Api-Key header is required to send this request." }
POST /extracted-text
Summary
Extract all text from a PDF, optionally including style and/or position information.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
full_text
Returns all text from the document without metadata, optionally split by page
Accepts:
off
by_page
document
document
No
word_style
Adds a JSON-formatted list of each word in the document with style information for each word, including font, size, color, and color-space. NOTE: Turning on word_style and word_coordinates will add both types of metadata to the same word list
Accepts:
off
on
off
No
word_coordinates
Adds a JSON-formatted list of each word in the document, including page and coordinates of all 4 corners of each word's bounding box. NOTE: Turning on word_style and word_coordinates will add both types of metadata to the same word list
Accepts:
off
on
off
No
output_type
Specify whether to save output as a file with .json extension or return output directly in the JSON response
Accepts:
json
file
json
No
output
Name of the generated output file (when output_type is set to file), without extension
{
"error": "Uploaded file is not valid input for this route. See documentation for valid file format(s)." }
401
Unauthorized
{
"error": "An Api-Key header is required to send this request." }
POST /pdf-with-ocr-text
Summary Uses Optical Character Recognition (OCR) technology to identify text within images embedded in PDFs. The detected text is then strategically placed behind the image within the PDF document.
This process results in a PDF with searchable and extractable text. Also works well as a pre-processing step before passing the PDF to the /extracted-text endpoint to extract PDF image text along with other document text.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
languages
Comma-separated list specifying the languages the OCR engine should recognize within the document
NOTE: Including many languages may effect performance, particularly CJK languages (Chinese, Japanese, Korean).
Accepts:
ChineseSimplified
ChineseTraditional
Dutch
English
French
German
Italian
Japanese
Korean
Portuguese
Spanish
Example: English,German,French
English
No
output
Name of the generated output file, without extension
{
"error": "This route will only accept a File or an ID, not both." }
401
Unauthorized
{
"error": "The input file is password protected and cannot be processed." }
POST /pdf
Summary Convert many types of files to PDF
Accepts all of the following input file types:
Microsoft Word (.doc, .docx)
Microsoft Excel (.xls, .xlsx)
Microsoft PowerPoint (.ppt, .pptx)
PostScript and Encapsulated PostScript (.ps, .eps)
JPEG (.jpg, .jpeg)
TIF (.tif, .tiff)
BMP (.bmp)
PNG (.png)
HTML (.html)
HTML (from URL)
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any file of supported type
Example: @PATH_TO_FILE/example_file.html
None
One of:
file
id
url
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
url
url
URL of web page to process
Accepts: Any valid URL
Example: https://en.wikipedia.org/wiki/Datalogics
None
One of:
file
id
url
output
Name of the generated output file, without extension
Accepts: Any valid file name
Example: example_out
[INPUT_FILE_NAME]_pdfrest_pdf
No
compression
Image compression for PostScript, Microsoft Office, HTML conversion
Accepts:
lossy
lossless
lossy
No
downsample
Downsample images during PostScript, Microsoft Office, HTML conversion or preserve original resolutions with the 'off' option
Accepts:
off
75
150
300
600
1200
300
No
tagged_pdf
Microsoft Office file conversion only: Create a tagged PDF document, required for accessibility compliance
Accepts:
on
off
off
No
locale
Microsoft Excel file conversion only: Set the UTF-8 Locale used for correctly displaying regional numerical and monetary values, time and date formats, and other locale-specific standards.
Accepts:
US - applies en_US
Germany - applies de_DE
Example: Germany
US
No
page_size
HTML conversion only: Select a page size for the PDF file. Options correspond to standard paper sizes
Accepts:
letter
legal
ledger
A3
A4
A5
letter
No
page_margin
HTML conversion only: Set margins for a PDF file in inches or millimeters
Accepts: A number followed by either 'in' or 'mm'
Example:
8mm
2.5in
10.25mm
0in
1in
No
page_orientation
HTML conversion only: Set the page orientation
Accepts:
portrait
landscape
portrait
No
web_layout
HTML conversion only: For web pages with responsive design, select the intended web layout
{
"error": "0 is not within the acceptable range for downsample." }
401
Unauthorized
{
"error": "The provided key is not valid." }
POST /pdfa
Summary Converts PDF to any of the following PDF/A versions:
PDF/A-1b - Basic conformance with visual appearance.
PDF/A-2b - Basic conformance with archival standards but revised for later versions of the PDF format. PDF/A-2 includes options for OpenType fonts, layers, attachments (which must also be PDF/A compliant) and JPEG 2000 image compression.
PDF/A-2u - Matches PDF/A-2b but also requires that all text in the document have Unicode mappings.
PDF/A-3b - Matches PDF/A-2b, except that it is possible to embed any kind of file in the PDF document. For example, with PDF/A-3 a user can save a XML, CSV, CAD, spreadsheet, or other type of file in the PDF document and be compliant. The file embedded in the PDF/A-3 does not need to PDF/A compliant.
PDF/A-3u - Matches PDF/A-3b, but also requires that all text in the document have Unicode mapping.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
output_type
Desired PDF/A version for the output PDF
Accepts:
PDF/A-1b
PDF/A-2b
PDF/A-2u
PDF/A-3b
PDF/A-3u
None
Yes
output
Name of the generated output file, without extension
Accepts: Any valid file name
Example: example_out
[INPUT_FILE_NAME]_pdfrest_pdfa
No
rasterize_if_errors_encountered
When set to ON, if the API finds errors when converting a PDF document, it will rasterize the page with the problem into a graphic image and continue to save the document as a PDF/A document. If set to OFF it will instead return an error in such cases.
{
"error": "PDF/A-2x is not within the acceptable range for output_type." }
401
Unauthorized
{
"error": "The input file is password protected and cannot be processed." }
POST /pdfx
Summary Converts PDF to any of the following PDF/X versions:
PDF/X-1a: This standard ensures that all fonts are embedded, and colors are specified in CMYK or spot colors. It's designed for reliable printing, ensuring that the document can be printed without any changes.
PDF/X-3: Similar to PDF/X-1a, but allows for the inclusion of color-managed data, such as RGB and ICC profiles. This provides more flexibility in color management while maintaining print reliability.
PDF/X-4: Builds on PDF/X-3 by supporting transparency and layers, as well as color-managed data. It's ideal for more complex print jobs that require these additional features.
PDF/X-6: The latest in the PDF/X series, designed to support modern print workflows with advanced features like variable data printing and enhanced color management, ensuring high-quality output in complex printing environments.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
output_type
Desired PDF/X version for the output PDF
Accepts:
PDF/X-1a
PDF/X-3
PDF/X-4
PDF/X-6
None
Yes
output
Name of the generated output file, without extension
{
"error": "This route will only accept a File or an ID, not both." }
401
Unauthorized
{
"error": "The input file is password protected and cannot be processed." }
POST /compressed-pdf
Summary Compresses a PDF to maximally reduce file size while maintaining usable content. Three preset compression levels are offered: low, medium, and high. These produce progressively smaller files with a tradeoff between fidelity and size reduction. Compression options may also be customized via a configurable JSON profile.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
compression_level
Degree of compression with a tradeoff between preserving fidelity (low) and maximizing file size reduction (high) NOTE: When custom is selected, profile parameter is required
Accepts:
low
medium
high
custom
None
Yes
profile
JSON profile to be uploaded with specifications for configurable compression settings
{
"error": "This route will only accept a File or an ID, not both." }
401
Unauthorized
{
"error": "The input file is password protected and cannot be processed." }
422
Unprocessable Entity
{
"error": "The 'profile' file provided is not a JSON file, please see documentation for sample profile." }
POST /watermarked-pdf
Summary
Apply either a text-based or an image-based watermark to all pages of a PDF with customizable font, text size, color, opacity, scale, positioning, and rotation.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
PDF file to be uploaded and watermarked
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
watermark_text
The text to apply to the input document as a watermark
Accepts: Any text string
Example: Property of ABC Company
None
One of:
watermark_text
watermark_file
watermark_file_id
watermark_file
PDF file to apply to the input document as a watermark
Accepts: Any PDF file (NOTE: to apply another graphic image format as a watermark, first convert that format to PDF with the /pdf endpoint)
Example: @PATH_TO_FILE/watermark_image.pdf
None
One of:
watermark_text
watermark_file
watermark_file_id
watermark_file_id
Alphanumeric ID (UUID) of existing PDF file on server to be applied as a watermark
Accepts: Any valid resource ID returned by a POST request
Example: 1f50b5bdf-0425-7d3f-1ea3-v2894f1ae833
None
One of:
watermark_text
watermark_file
watermark_file_id
output
Name of the generated output file, without extension
Comma separated Red, Green, Blue values for a text watermark NOTE: cannot be used with text_color_cmyk
Accepts: Each value must be between 0 and 255
Example: 255,0,0
0,0,0
No
text_color_cmyk
Comma separated Cyan, Magenta, Yellow, Key (Black) values for a text watermark NOTE: cannot be used with text_color_rgb
Accepts: Each value must be between 0 and 100
Example: 100,0,0,0
None
No
watermark_file_scale
Scale applied to resize the content of a pdf watermark file
Accepts: Any non-negative number
Example: 2.25
0.5
No
opacity
Opacity value for both text and file watermarks
Accepts: Any decimal value from 0 to 1, where 0 is fully transparent and 1 is fully opaque
Example: 0.75
0.5
No
horizontal_alignment
Select the horizontal position of your watermark relative to the page edges. This starting alignment can be further offset with the vertical_alignment, x, and y parameters.
Accepts:
left: Aligns the watermark to the left edge of the page.
right: Aligns the watermark to the right edge of the page.
center: Centers the watermark horizontally on the page.
Example: right
center
No
vertical_alignment
Select the vertical position of your watermark relative to the page edges. This starting alignment can be further offset with the horizontal_alignment, x, and y parameters.
Accepts:
top: Aligns the watermark to the top edge of the page.
bottom: Aligns the watermark to the bottom edge of the page.
center: Centers the watermark vertically on the page.
Example: top
center
No
x
Horizontal offset in PDF units from the selected 'horizontal_alignment' for both text and file watermarks (72 units = 1 inch)
Accepts: Any integer value
Example: -72
0 (horizontal center of page)
No
y
Vertical offset in PDF units from the selected 'vertical_alignment' for both text and file watermarks (72 units = 1 inch)
Accepts: Any integer value
Example: 150
0 (vertical center of page)
No
rotation
Rotation in degrees to be applied to both text and file watermarks
Accepts: Any integer value
Example: 45
0
No
Responses
Response Status Code
Description
JSON Response Example
200
OK
NOTE: inputId always returns the resource ID of the input PDF to be watermarked. When a file is used as a watermark, inputID returns an array with the resource ID of the input PDF that was watermarked first and the resource ID of the input file that was applied as a watermark second.
{
"error": "The requested font was not found. Please see the documentation for a list of accepted fonts." }
401
Unauthorized
{
"error": "The input file was corrupted, password-protected, or not a PDF." }
POST /encrypted-pdf
Summary
Encrypt a PDF using 256-bit AES encryption with a 32-bit key. Encrypted PDFs cannot be viewed without first providing the open password.
Use "current_open_password" with "new_open_password" to change the open password on a document that was already encrypted. Use "current_permissions_password" if the input document has a permissions password.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
new_open_password
New open password
Accepts: A string between 6 and 128 characters long
Example: 1234567890qwertyuiop
None
Yes
current_open_password
Existing open password
Accepts: A valid password
Example: OpenUp
None
No
current_permissions_password
Existing permissions password
Accepts: A valid password
Example: oahfoufdo99
None
No
output
Name of the generated output file, without extension
{
"error": "A password is required to process the document." }
401
Unauthorized
{
"error": "The input file was corrupted, password-protected, or not a PDF." }
POST /restricted-pdf
Summary
Apply one or more document security restrictions to PDF with a permissions password. At minimum, a permissions password prevents the security settings of a document from being modified. Use "restrictions[]" to add additional security restrictions.
Use "current_permissions_password" with "new_permissions_password" to change the permissions password on a document.
NOTE: Setting a new permissions password will normally overwrite existing security data, including the open password. Use "current_open_password" to keep encryption with an already applied open password.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
new_permissions_password
New permissions password
Accepts: A string between 6 and 128 characters long
Example: igy4e5ds7g87646fYFtfTFdh78g6DR
None
Yes
current_permissions_password
Existing permissions password
Accepts: A valid password
Example: passwordpassword123
None
No
restrictions[]
Document restrictions to be applied. Restricted operations are locked behind the permissions password when interacting with a restricted document.
Accepts:
print_low
print_high
edit_document_assembly
edit_fill_and_sign_form_fields
edit_annotations
edit_content
copy_content
accessibility_off
Example: edit_content
None
No
current_open_password
Existing open password
Accepts: A valid password
Example: openfileplease
None
No
output
Name of the generated output file, without extension
{
"error": "This route will only accept a File or an ID, not both." }
401
Unauthorized
{
"error": "The input file was corrupted, password-protected, or not a PDF." }
POST /unrestricted-pdf
Summary
Remove all document security restrictions from a PDF.
NOTE: Removing the permissions password will normally remove all existing security data, including the open password. Use "current_open_password" to keep encryption with an already applied open password.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
current_permissions_password
Existing permissions password
Accepts: A valid password
Example: kugdi9785gudw242FGdfdh
None
Yes
current_open_password
Existing open password
Accepts: A valid password
Example: thisIsThePassword
None
No
output
Name of the generated output file, without extension
{
"error": "This route will only accept a File or an ID, not both." }
401
Unauthorized
{
"error": "Cannot process the given input file without the correct permissions password." }
POST /merged-pdf
Summary Merges multiple PDF documents or specified pages from PDF documents into a single PDF document. Any number of PDFs may be merged by specifying "file" and/or "id[]" paramaters multiple times. Files will be merged in the order they are specified.
NOTE: For each included "file" or "id[]" a corresponding "pages[]" and "type[]" must also be included to correspond to the type and desired page(s) for that input file.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and merged with other files. This parameter may be included multiple times to specify multiple files to be merged.
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One or more of:
file
id[]
id[]
Alphanumeric ID (UUID) of existing file on server to be merged with other files. This parameter may be included multiple times to specify multiple files to be merged.
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One or more of:
file
id[]
pages[]
Page or range of pages to include in merged file. This parameter must be specified for each "file" and "id[]" specified.
Accepts: Any mix of individual pages and/or ranges seperated by commas. "last" can be used to represent the number of the last page of the document. Page order can be reversed using ranges with the higher number specified before the lower number.
Example:
14-last
9-2
1,2,5-10,12-last
even
odd
None
Yes
type[]
This parameter must be specified for each "file" and "id[]" specified and indicates whether a document is a new file to upload or an id for an existing file on the server. This is required to maintain the order of documents to merge.
Accepts:
file
id
None
Yes
output
Name of the generated output file, without extension
Summary Splits a single PDF document into one or more PDF documents with specified pages. Any number of PDFs may be split out from the original PDF by including "pages[]" multiple times. Output files will be returned in the order they are included.
NOTE: If "pages[]" is not specified, an output file will be created for each page of the input file containing only that page. A ten page PDF would be split into ten single-page PDFs.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and split into new files.
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be split into new files.
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
pages[]
Page or range of pages to include in output file. This parameter may be specified multiple times to create multiple output files. If this paramater is not specified, an output file will be created for each page of the input file containing only that page.
Accepts: Any mix of individual pages and/or ranges seperated by commas. "last" can be used to represent the number of the last page of the document. Page order can be reversed using ranges with the higher number specified before the lower number.
Example:
14-last
2-9
1,2,10-5,12-last
even
odd
None
No
output
Prefix of the generated output file name(s), without extension. A sequentially incremented number will be appended to the end of this prefix for each output file name along with a .pdf extension.
{
"error": "This route will only accept a File or an ID, not both." }
401
Unauthorized
{
"error": "The provided key is not valid." }
POST /pdf-with-added-text
Summary Inserts text blocks into a PDF at specified locations with custom settings for font and styling. NOTE: The PDF coordinate system places the origin in the lower-left corner. Coordinates are in PDF units (1 in. = 72 PDF units). Please note that PDFs with offset origins may create an offset in the placement of the text.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
PDF file to be uploaded for text to be added.
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing PDF file on server for text to be added.
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
text_objects
JSON-formatted string consisting of an array of one or more objects containing options to add and format text.
Accepts:
font - String | Required | Specify the font of the given string. See Font List for a complete list.
max_width - String | Required | The maximum width of the text column in PDF Units (72 PDF Units = 1 inch). The text will wrap to conform to this width.
page - String | Required | Page number on which to add text. You can provide a page number, or you can use "all" to add the text to every page at the same X/Y position.
rotation - String | Required | Rotation in degrees of the text block
text - String | Required | String of text to add
text_color_cmyk or text_color_rgb - String | Required | Comma-delineated string of color values (RGB example - "53,5,102", CMYK example - "0,100,100,0"). Use one of these to set the text color.
text_size - String | Required | Font size of the text (5 - 100)
x - String | Required | Horizontal starting position of the text in PDF Units (72 PDF Units = 1 inch)
y - String | Required | Vertical starting position of the text in PDF Units (72 PDF Units = 1 inch)
is_rtl - String | Optional | Set to "true" to insert right-to-left (RTL) language text
{
"error": "The requested font was not found. Please see the documentation for a list of accepted fonts." }
401
Unauthorized
{
"error": "The provided key is not valid." }
POST /pdf-with-added-image
Summary Inserts an image into one page of a PDF at a specified location. Accepted image formats:
JPEG (.jpg, .jpeg)
TIF (.tif, .tiff)
PNG (.png)
GIF (.gif)
NOTE: The PDF coordinate system places the origin in the lower-left corner. Coordinates are in PDF units (1 in. = 72 PDF units). Please note that PDFs with offset origins may create an offset in the placement of the image.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
PDF file to be uploaded for an image to be added.
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing PDF file on server for an image to be added.
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
image_file
Image file to be uploaded and added to the PDF.
Accepts: Any image file of supported format (JPEG, TIFF, PNG, GIF).
Example: @PATH_TO_FILE/add_this.jpg
None
One of:
image_file
image_id
image_id
Alphanumeric ID (UUID) of existing image file on server to be added to the PDF.
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
image_file
image_id
x
Horizontal position of the image (by its lower-left corner) in PDF units (72 PDF units = 1 inch)
Accepts: Any integer value
Example: 72
None
Yes
y
Vertical position of the image (by its lower-left corner) in PDF units (72 PDF units = 1 inch)
Accepts: Any integer value
Example: 144
None
Yes
page
Page of the PDF to add the image into
Accepts: Any valid page number for the PDF file being processed
Example: 1
None
Yes
output
Name of the generated output file, without extension.
Accepts: Any valid file name
Example: example_out
[INPUT_FILE_NAME]_pdfrest_pdf-with-added-image
No
Responses
Response Status Code
Description
JSON Response Example
200
OK
NOTE: inputId is an array of 2 elements where the first element is the resource ID of the input PDF and the second element is the resource ID of the input image file.
NOTE: inputId is an array of 2 elements where the first element is the resource ID of the input PDF and the second element is the resource ID of the attached input file.
{
"error": "The input PDF file claims conformance to a version of PDF/A that prohibits file attachments." }
401
Unauthorized
{
"error": "The provided key is not valid." }
POST /bmp
Summary Convert PDF to BMP image files, one per PDF page
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
output
Prefix of the generated output file name(s), without extension. A sequentially incremented number will be appended to the end of this prefix for each output file name along with a .bmp extension.
Accepts: Any valid file name
Example: example_out
[INPUT_FILE_NAME]_pdfrest_bmp
No
pages
Page or range of pages to process
Accepts: Any mix of individual pages and/or ranges seperated by commas. "last" can be used to represent the number of the last page of the document.
{
"error": "0 is not within the acceptable range for resolution." }
401
Unauthorized
{
"error": "The input file is password protected and cannot be processed." }
POST /jpg
Summary Convert PDF to JPEG image files, one per PDF page
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
output
Prefix of the generated output file name(s), without extension. A sequentially incremented number will be appended to the end of this prefix for each output file name along with a .jpg extension.
Accepts: Any valid file name
Example: example_out
[INPUT_FILE_NAME]_pdfrest_jpg
No
pages
Page or range of pages to process
Accepts: Any mix of individual pages and/or ranges seperated by commas. "last" can be used to represent the number of the last page of the document.
Example:
14-last
2-9
1,2,5-10,12-last
1-last (all pages)
No
resolution
Output image resolution in Dots Per Inch (DPI)
Accepts: 12 to 2400
300
No
color_model
Color model of the output file
Accepts:
rgb
cmyk
gray
rgb
No
jpeg_quality
JPEG compression quality. Higher values produce a higher quality image but also a larger output file size.
{
"error": "0 is not within the acceptable range for resolution." }
401
Unauthorized
{
"error": "The input file is password protected and cannot be processed." }
POST /png
Summary Convert PDF to PNG image files, one per PDF page
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
output
Prefix of the generated output file name(s), without extension. A sequentially incremented number will be appended to the end of this prefix for each output file name along with a .png extension.
Accepts: Any valid file name
Example: example_out
[INPUT_FILE_NAME]_pdfrest_png
No
pages
Page or range of pages to process
Accepts: Any mix of individual pages and/or ranges seperated by commas. "last" can be used to represent the number of the last page of the document.
{
"error": "0 is not within the acceptable range for resolution." }
401
Unauthorized
{
"error": "The input file is password protected and cannot be processed." }
POST /gif
Summary Convert PDF to GIF image files, one per PDF page
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
output
Prefix of the generated output file name(s), without extension. A sequentially incremented number will be appended to the end of this prefix for each output file name along with a .gif extension.
Accepts: Any valid file name
Example: example_out
[INPUT_FILE_NAME]_pdfrest_gif
No
pages
Page or range of pages to process
Accepts: Any mix of individual pages and/or ranges seperated by commas. "last" can be used to represent the number of the last page of the document.
{
"error": "0 is not within the acceptable range for resolution." }
401
Unauthorized
{
"error": "The input file is password protected and cannot be processed." }
POST /tif
Summary Convert PDF to TIFF image files, one per PDF page
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
output
Prefix of the generated output file name(s), without extension. A sequentially incremented number will be appended to the end of this prefix for each output file name along with a .tif extension.
Accepts: Any valid file name
Example: example_out
[INPUT_FILE_NAME]_pdfrest_tif
No
pages
Page or range of pages to process
Accepts: Any mix of individual pages and/or ranges seperated by commas. "last" can be used to represent the number of the last page of the document.
{
"error": "0 is not within the acceptable range for resolution." }
401
Unauthorized
{
"error": "The input file is password protected and cannot be processed." }
POST /pdf-with-converted-colors
Summary Convert PDF colors with precise document color control through custom ICC profiles and a library of print, screen, web, and grayscale presets.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
color_profile
Choose from any of the preset color profiles, or select custom to supply an ICC color profile
Accepts:
lab-d50 - L*a*b color specification with a D50 white point. The Lab color space is based on the CIE XYZ color space, but it includes a dimension L, for lightness, along with a and b coordinates, to define the color. This is Adobe Systems’ standard Lab profile.
srgb - Standard RGB, the default profile for Windows monitors.
apple-rgb - Apple RGB, the default profile for Mac monitors
color-match-rgb - Color Match RGB. This is a simpler version of the Radius ColorMatch RGB space, without the non-zero black point.
gamma-18 - Gray Gamma 1.8, grayscale display profile, used for content viewed on a monitor
gamma-22 - Gray Gamma 2.2
dot-gain-10 - Grayscale printer profile, with dot gain 10%. Dot gain is commonly used in offset printing to define the increase in size in halftone dots in the printing process, making a printed document look darker than intended.
dot-gain-15 - Dot gain 15%
dot-gain-20 - Dot gain 20%
dot-gain-25 - Dot gain 25%
dot-gain-30 - Dot gain 30%
monitor-rgb - RGB Monitor, referring to a monitor that requires separate signals for the three primary colors.
acrobat5-cmyk - Adobe Reader 5 CMYK
acrobat9-cmyk - Adobe Reader 9 CMYK
custom - supply a custom ICC color profile with either the profile or profile_id parameter
Example: acrobat9-cmyk
None
Yes
profile
Select a local ICC color profile document to upload for processing.
NOTE: If color_profile is set to custom then a custom ICC color profile must be supplied with either the profile or profile_id paramater.
Accepts: Any valid ICC color profile
Example: @PATH_TO_FILE/example_profile.icc
None
When color_profile is set to custom, one of:
profile
profile_id
profile_id
Submit a resource ID for an ICC color profile document that already exists on the processing server.
NOTE: If color_profile is set to custom then a custom ICC color profile must be supplied with either the profile or profile_id paramater.
Accepts: Any valid resource ID returned by a POST request
Example: 138aadb71-ee34-4621-9098-9686441e84e2
None
When color_profile is set to custom, one of:
profile
profile_id
output
Name of the generated output file, without extension
{
"error": "This route will only accept a File or an ID, not both." }
401
Unauthorized
{
"error": "The input file is password protected and cannot be processed." }
POST /pdf-with-imported-form-data
Summary
Import data from a file into an Acroform or XFA-based PDF form. This will find matching form fields in the PDF and fill those fields with the corresponding data from the data file.
Accepted data file formats vary, depending on the form type in the input PDF:
Acroform: .fdf, .xfdf, .xml
XFA: .xdp, .xfd, .xml
If you are unsure which form type is being used, try processing the PDF with Query PDF to run the contains_acroforms and contains_xfa checks.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file containing forms with edit permissions active
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing PDF on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
data_file
Data file to be uploaded in order to import its data to an input PDF file
Accepts: Accepted data file formats vary, depending on the form type in the input PDF:
Acroform: .fdf, .xfdf, .xml
XFA: .xdp, .xfd, .xml
Example: @PATH_TO_FILE/example_file.xml
None
One of:
data_file
data_file_id
data_file_id
Alphanumeric ID (UUID) of existing data file on server
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
data_file
data_file_id
output
Name of the generated output file, without extension
{
"error": "Input PDF contains XFA form fields. Valid options for data_format are: xfd, xdp, xml" }
401
Unauthorized
{
"error": "An Api-Key header is required to send this request." }
POST /pdf-with-acroforms
Summary Convert XFA forms to Acroforms. This significantly improves compatibility, allowing forms to be accessed and edited across a wide range of PDF readers and applications.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
output
Name of the generated output file, without extension
{
"warning": "No XFA forms were detected in the input PDF. No output was produced." }
400
Bad Request
{
"error": "This route will only accept a File or an ID, not both." }
401
Unauthorized
{
"error": "An Api-Key header is required to send this request." }
POST /flattened-forms-pdf
Summary Flatten all forms in a PDF, including both static and dynamic XFA and AcroForms. This makes form fields no longer editable while preserving form field data. It also ensures that PDFs with forms are compatible with all standard PDF viewers and processing tools.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
output
Name of the generated output file, without extension
{
"error": "This route will only accept a File or an ID, not both." }
401
Unauthorized
{
"error": "The input file is password protected and cannot be processed." }
POST /flattened-transparencies-pdf
Summary Flatten all transparent objects in a PDF to increase RIP speed in a prepress workflow and to enable compatibility for workflows in which transparency is not supported.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and processed
Accepts: Any PDF file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be processed
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
output
Name of the generated output file, without extension
{
"error": "This route will only accept a File or an ID, not both." }
401
Unauthorized
{
"error": "The input file is password protected and cannot be processed." }
POST /upload
Summary Upload any number of files from local storage or via public URL by specifying "file" or "url" paramaters one or more times.
Examples
Required Headers
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
To upload more than one file with a single call:
Accept: application/json
Content-Type: multipart/form-data
To upload one file with a binary payload (replace file.pdf with the file's actual name and extension):
Content-Type: application/octet-stream
Content-Filename: 'file.pdf'
Body Parameters
Name
Description
Default
Required
file
File to be uploaded. This parameter may be included multiple times to upload multiple files but may not be combined with 'url' parameter.
Accepts: Any file of supported type
Example: @PATH_TO_FILE/example_file.pdf
None
One or more: file - OR - One or more: url
url
Public URL address for a file. This parameter may be included multiple times to upload multiple files from different URLs but may not be combined with 'file' parameter.
{
"error": "Files and URLs cannot be uploaded together." }
401
Unauthorized
{
"error": "The provided key is not valid." }
POST /zip
Summary Compress any number of files into a .zip by specifying "file" and/or "id[]" paramaters multiple times.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and zipped with other files. This parameter may be included multiple times to compress multiple files to a .zip file.
Accepts: Any file of supported type
Example: @PATH_TO_FILE/example_file.pdf
None
One or more of:
file
id[]
id[]
Alphanumeric ID (UUID) of existing file on server to be zipped with other files. This parameter may be included multiple times to compress multiple files to a .zip file.
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One or more of:
file
id[]
output
Name of the generated output file, without extension
{
"error": "Found more than one output key, only one is allowed." }
401
Unauthorized
{
"error": "The provided key is not valid." }
POST /unzip
Summary Extract files from a compressed .zip archive, providing resource IDs for each unzipped file, which can then be processed or downloaded individually. Optionally accepts a password to support unzipping password-protected .zip archives.
Examples
Required Headers
Accept: application/json
Content-Type: multipart/form-data
Api-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Body Parameters
Name
Description
Default
Required
file
File to be uploaded and unzipped.
Accepts: Any .zip file
Example: @PATH_TO_FILE/example_file.pdf
None
One of:
file
id
id
Alphanumeric ID (UUID) of existing file on server to be unzipped.
Accepts: Any valid resource ID returned by a POST request
Example: 0950b9bdf-0465-4d3f-8ea3-d2894f1ae839
None
One of:
file
id
password
Optional password to unlock protected .zip archives