PDFreactor Web Service Conversion REST API (11.4.0)

This is the conversion REST API definition and documentation of the PDFreactor Web Service.

Convert synchronously

post /convert
http://localhost:9423/service/rest/convert
https://cloud.pdfreactor.com/service/rest/convert

Converts the specified configuration or asset package into PDF or image and returns the generated PDF or image.

query Parameters
apiKey
string

The API key to authenticate the request (only necessary if the server is appropriately configured).

Request Body schema:
addAttachments
boolean

Enables or disables attachments specified in style sheets.

The default value is false.

addBookmarks
boolean
Deprecated

Deprecated as of PDFreactor 11. Use disableBookmarks instead.

addComments
boolean

Enables or disables comments in the PDF document.

The default value is false.

addLinks
boolean
Deprecated

Deprecated as of PDFreactor 11. Use disableLinks instead.

addOverprint
boolean

Enables or disables overprinting.

The default value is false.

addPreviewImages
boolean

Enables or disables embedding of image previews per page in the PDF document.

The default value is false.

addTags
boolean

Enables or disables tagging of the PDF document.

The default value is false.

allowAnnotations
boolean

Enables or disables the 'annotations' restriction in the PDF document.

The default value is false.

allowAssembly
boolean

Enables or disables the 'assembly' restriction in the PDF document.

The default value is false.

allowCopy
boolean

Enables or disables the 'copy' restriction in the PDF document.

The default value is false.

allowDegradedPrinting
boolean

Enables or disables the 'degraded printing' restriction in the PDF document.

The default value is false.

allowFillIn
boolean

Enables or disables the 'fill in' restriction in the PDF document.

The default value is false.

allowModifyContents
boolean

Enables or disables the 'modify contents' restriction in the PDF document.

The default value is false.

allowPrinting
boolean

Enables or disables the 'printing' restriction in the PDF document.

The default value is false.

allowScreenReaders
boolean

Enables or disables the 'screen readers' restriction in the PDF document.

The default value is false.

appendLog
boolean

Specifies whether or not the log data should be added to the PDF document.

The default value is false.

attachments
Array of objects (Attachment)

Adds a file attachment to PDF document.

authenticationCredentials
object (KeyValuePair)
author
string

Sets the value of the author field of the PDF document.

baseUrl
string

Sets the base URL of the document.

To resolve relative URLs to absolute URLs a reference (base) URL is required. This reference URL is usually the system id of the document.

This method can be used to specify another reference URL. If this URL is not null then it will be used instead of the system id.

The default value is null.

baseURL
string
Deprecated

Deprecated as of PDFreactor 11. Use baseUrl instead.

bookletMode
object (BookletMode)
callbacks
Array of objects (Callback)

Adds callbacks to the conversion which will be called at specific times. All callbacks perform a POST request to the specified URL with the specified content type and a certain model which depends on the callback event.

For each callback, you can specify a timeout. If no timeout is specified, the server's default timeout for callbacks is used. A value of zero or negative values indicate an infinite timeout, however the PDFreactor server may have a maximum timeout configured, in which case that will be the used value.

Some callbacks might be called regularly during the course of a conversion. For these callbacks you can specify an interval to control how frequently they are called.

cleanupTool
string (Cleanup)
Enum: "CYBERNEKO" "JTIDY" "NONE" "TAGSOUP"
colorSpaceSettings
object (ColorSpaceSettings)
conformance
string (Conformance)
Enum: "PDF" "PDFA1A" "PDFA1A_PDFUA1" "PDFA1B" "PDFA2A" "PDFA2A_PDFUA1" "PDFA2B" "PDFA2U" "PDFA3A" "PDFA3A_PDFUA1" "PDFA3B" "PDFA3U" "PDFUA1" "PDFX1A_2001" "PDFX1A_2003" "PDFX3_2002" "PDFX3_2003" "PDFX4" "PDFX4P"
contentObserver
object (ContentObserver)
continuousOutput
object (ContinuousOutput)
conversionName
string

Sets a name for the conversion. If a name is set, it will be logged at level "info". The name can be an arbitrary string but should be unique for every conversion or application so that the log output can be matched to a specific conversion or application later.

conversionTimeout
integer

Sets a timeout in seconds for the whole document conversion. If the timeout is exceeded, the conversion will be aborted.

A timeout of 0 or negative values mean that the conversion will never time out. This is also the default behavior if no timeout is specified.

cookies
Array of objects (KeyValuePair)

Adds a cookie to all outgoing HTTP connections. The parameters are URL encoded (see rawCookies). If the key already exists, the pair is overwritten.

creator
string

Sets the value of creator field of the PDF document.

cssSettings
object (CssSettings)
customDocumentProperties
Array of objects (KeyValuePair)

Adds a custom property to the PDF document. An existing property of the same name will be replaced.

debugSettings
object (DebugSettings)
defaultColorSpace
string (ColorSpace)
Enum: "CMYK" "RGB"
disableBookmarks
boolean

Disables bookmarks in the PDF document.

The default value is false.

disableFontEmbedding
boolean

Sets whether fonts will not be embedded into the resulting PDF. Setting this to true will reduce the file size of the output document. However, the resulting PDF documents are no longer guaranteed to look identical on all systems.

The default value is false.

disableLinks
boolean

Disables links in the PDF document.

The default value is false.

document
required
string or string or string

The input document. This can either be a URL string, XML or HTML source code string.

documentDefaultLanguage
string

Sets the language used for documents having no explicit language attribute set.

The language code is used to resolve the lang() selector correct and to determine the correct language used for hyphenation.

documentType
string (Doctype)
Enum: "AUTODETECT" "HTML5" "XHTML" "XML"
enableDebugMode
boolean
Deprecated

Deprecated as of PDFreactor 10. Use debugSettings instead.

encoding
string

Sets the encoding of the document.

If this value is set to null or it is empty then the encoding will be detected automatically.

The default value is null.

encryption
string (Encryption)
Enum: "NONE" "TYPE_128" "TYPE_40"
errorPolicies
Array of strings (ErrorPolicy)
Items Enum: "CONFORMANCE_VALIDATION_UNAVAILABLE" "LICENSE" "MISSING_RESOURCE" "UNCAUGHT_JAVASCRIPT_EXCEPTION"

Specifies error policies that will be used for the conversion. Depending on the policy, the conversion will fail if the appropriate criteria are not met.

fontAliases
Array of objects (Font)

Registers an alias font family for an existing font.

This function is limited to fonts loaded automatically from system folders.

fontFallback
Array of strings

Sets a list of fallback font families used for character substitution. This list is iterated for characters that can not be displayed with any of the fonts specified via the CSS property font-family.

fonts
Array of objects (Font)

Loads a font from a URL which can be used via the CSS property font-family.

forceGrayscaleImage
boolean

If the output format is an image format, this setting controls whether a grayscale image should be returned. This can not be combined with transparency.

fullCompression
boolean

Enables or disables full compression of the PDF document.

The default value is false.

httpsMode
string (HttpsMode)
Enum: "LENIENT" "STRICT"
ignoreAlpha
boolean

Sets whether the alpha value of CSS RGBA colors is ignored. This can be used to avoid conformance issues in PDF/A-1.

inspectableSettings
object (InspectableSettings)
integrationStyleSheets
Array of objects (Resource)

Adds an integration style sheet to the document.

There are two ways to specify the style sheet:

  1. Specifying the style sheet only using an URI.
  2. Specifying the style sheet by the content of the style sheet and alternatively setting a URI to resolve relative elements. If no URI is specified then the system id/base URL of the document will be used.
javaScriptMode
string (JavaScriptMode)
Enum: "DISABLED" "ENABLED" "ENABLED_NO_LAYOUT" "ENABLED_REAL_TIME" "ENABLED_TIME_LAPSE"
javaScriptSettings
object (JavaScriptSettings)
keepDocument
boolean

If set to true prevents the document from being deleted from the PDFreactor Web Service after it has been accessed. This only works for asynchronous conversions.

keywords
string

Sets the value of the keywords field of the PDF document.

licenseKey
string

Sets the license key either as content or URL. If the license key is set to null then PDFreactor looks for a license key file file in the same directory where the 'pdfreactor.jar' file is located. If no license key could be found then PDFreactor runs in evaluation mode.

The default value is null.

logExceedingContent
object (LogExceedingContent)
logLevel
string (LogLevel)
Enum: "DEBUG" "FATAL" "INFO" "NONE" "PERFORMANCE" "WARN"
logMaxLines
integer

Sets the maximum amount of log entries that will be retained by the PDFreactor logs.

The default value is 100000.

A capacity of 0 is equivalent to the default value. A negative value means that the capacity will be unlimited.

mediaFeatureValues
Array of objects (MediaFeatureValue)

Defines the value of a Media Feature which is used to resolve CSS3 media queries.

mediaTypes
Array of strings

Sets the media types that are used to resolve CSS3 media queries.

Please note that this overrides the default media types of PDFreactor, which are:

"print", "paged", "visual", "bitmap", "static", "-ro-pdfreactor"

mergeByteArray
string <base64>
Deprecated

Deprecated as of PDFreactor 9. Use mergeDocuments instead.

mergeByteArrays
Array of strings <base64>
Deprecated

Deprecated as of PDFreactor 9. Use mergeDocuments instead.

mergeDocuments
Array of objects (Resource)

This method sets external PDF documents which will be merged with the PDF document generated by the HTML source.

mergeMode
string (MergeMode)
Enum: "APPEND" "ARRANGE" "OVERLAY" "OVERLAY_BELOW" "PREPEND"
mergeURL
string
Deprecated

Deprecated as of PDFreactor 9. Use mergeDocuments instead.

mergeURLs
Array of strings
Deprecated

Deprecated as of PDFreactor 9. Use mergeDocuments instead.

outputFormat
object (OutputFormat)
outputIntent
object (OutputIntent)
overlayRepeat
string (OverlayRepeat)
Enum: "ALL_PAGES" "LAST_PAGE" "NONE" "TRIM"
ownerPassword
string

Sets the owner password of the PDF document.

The default value is null.

pageOrder
PageOrder (string) or string

Sets the page order of the direct result of the conversion.

If mergeMode is set to "ARRANGE", this method is also used to specify the position of inserted pages from an existing PDF.

A description of the syntax can be found in the manual.

pagesPerSheetProperties
object (PagesPerSheetProperties)
pdfScriptAction
Array of objects (PdfScriptAction)

Sets a pair of trigger event and PDF script. The script is triggered on the specified event.

A PDF script is JavaScript that is executed by a PDF viewer (e.g. Adobe Reader). Note that most viewers do not support this feature.

PDF Scripts can also be set by using the proprietary CSS property pdf-script-action. More information on this property can be found in the manual.

Please note, that scripts set via CSS have a higher priority. If two scripts are registered on the same event, but one via API and the other via the CSS property, the script set in the CSS will override the other one.

pixelsPerInch
integer

Sets the pixels per inch.

Changing this value changes the physical length of sizes specified in px (including those specified via HTML attributes).

The default value is 96 ppi.

pixelsPerInchShrinkToFit
boolean

Whether the pixels per inch should be adapted automatically to avoid content exceeding pages.

postTransformationDocumentType
string (Doctype)
Enum: "AUTODETECT" "HTML5" "XHTML" "XML"
printDialogPrompt
boolean

Enables or disables a print dialog to be shown upon opening the generated PDF document by a PDF viewer.

The default value is false.

processingPreferences
Array of strings (ProcessingPreferences)
Items Value: "SAVE_MEMORY_IMAGES"

Preferences that influence the conversion process without changing the output.

Use the ProcessingPreferences constants to specify the processing preferences. By default no processing preference is set.

quirksSettings
object (QuirksSettings)
rawCookies
Array of objects (KeyValuePair)

Adds a cookie to all outgoing HTTP connections. The parameters are not URL encoded (see cookies). If the key already exists, the pair is overwritten.

requestHeaders
Array of objects (KeyValuePair)

Adds a request header to all outgoing HTTP connections. If the key already exists, the pair is overwritten.

requestPriority
integer

Specifies the priority of the conversion request. A higher priority means that the web service will adjust the conversion's position in the queue appropriately, so that it is converted before others with lower priority.

By default, asynchronous conversions have a priority of 0, synchronous conversions have a priority of 10.

resourceConnectTimeout
integer

Sets a timeout in milliseconds for connecting to resources, such as HTTP requests to style sheets, images etc. If the connection could not be established until the timeout expires, the request will be aborted and the resource will not be loaded.

A timeout of 0 means that the connection will not time out. A negative value means that no timeout will be set. The default value is 60000 (1min).

resourceReadTimeout
integer

Sets a timeout in milliseconds for reading resources, such as HTTP requests to style sheets, images etc. If the download does not start until the timeout expires, the request will be aborted and the resource will not be loaded.

A timeout of 0 means that the download will not time out. A negative value means that no timeout will be set. The default value is 60000 (1min).

resourceRequestTimeout
integer
Deprecated

Deprecated as of PDFreactor 10. Use resourceConnectTimeout and resourceReadTimeout instead.

segmentationSettings
object (SegmentationSettings)
signPDF
object (SignPDF)
subject
string

Sets the value of the subject field of the PDF document.

throwLicenseExceptions
boolean
Deprecated

Deprecated as of PDFreactor 9. Use errorPolicies instead.

title
string

Sets the value of the title field of the PDF document.

urlRewriteSettings
object (UrlRewriteSettings)
userPassword
string

Sets the user password of the PDF document.

The default value is null.

userScripts
Array of objects (Resource)

Adds an user script to the document.

There are two ways to specify the script:

  1. Specifying the script only by an URI.
  2. Specifying the script by the content of the script and alternatively setting a URI to resolve relative elements. If no URI is specified then the system id/base URL of the document will be used.
userStyleSheets
Array of objects (Resource)

Adds a user style sheet to the document.

There are two ways to specify the style sheet:

  1. Specifying the style sheet only using an URI.
  2. Specifying the style sheet by the content of the style sheet and alternatively setting a URI to resolve relative elements. If no URI is specified then the system id/base URL of the document will be used.
validateConformance
boolean

Enables PDFreactor to validate the generated PDF against the Conformance specified via conformance.

Currently only PDF/A and PDF/UA validation is supported.

Please note that validation might take several minutes for larger documents.

viewerPreferences
Array of strings (ViewerPreferences)
Items Enum: "CENTER_WINDOW" "DIRECTION_L2R" "DIRECTION_R2L" "DISPLAY_DOC_TITLE" "DUPLEX_FLIP_LONG_EDGE" "DUPLEX_FLIP_SHORT_EDGE" "DUPLEX_SIMPLEX" "FIT_WINDOW" "HIDE_MENUBAR" "HIDE_TOOLBAR" "HIDE_WINDOW_UI" "NON_FULLSCREEN_PAGE_MODE_USE_NONE" "NON_FULLSCREEN_PAGE_MODE_USE_OC" "NON_FULLSCREEN_PAGE_MODE_USE_OUTLINES" "NON_FULLSCREEN_PAGE_MODE_USE_THUMBS" "PAGE_LAYOUT_ONE_COLUMN" "PAGE_LAYOUT_SINGLE_PAGE" "PAGE_LAYOUT_TWO_COLUMN_LEFT" "PAGE_LAYOUT_TWO_COLUMN_RIGHT" "PAGE_LAYOUT_TWO_PAGE_LEFT" "PAGE_LAYOUT_TWO_PAGE_RIGHT" "PAGE_MODE_FULLSCREEN" "PAGE_MODE_USE_ATTACHMENTS" "PAGE_MODE_USE_NONE" "PAGE_MODE_USE_OC" "PAGE_MODE_USE_OUTLINES" "PAGE_MODE_USE_THUMBS" "PICKTRAYBYPDFSIZE_FALSE" "PICKTRAYBYPDFSIZE_TRUE" "PRINTSCALING_APPDEFAULT" "PRINTSCALING_NONE"

Sets the page layout and page mode preferences of the PDF.

Use the ViewerPreferences constants to specify the viewer preferences. By default no viewer preference is set.

xmp
object (Xmp)
xsltMode
boolean

Enables or disables XSLT transformations.

Set this value to true to enable XSLT transformations or to false to disable XSLT transformations.

The default value is false.

xsltStyleSheets
Array of objects (Resource)

Adds an XSLT style sheet to the document.

There are two ways to specify the style sheet:

  1. Specifying the style sheet only by an URI.
  2. Specifying the style sheet by the content of the style sheet and alternatively setting a URI to resolve relative elements. If no URI is specified then the system id/base URL of the document will be used.

Responses

200

Conversion successful

400

Multiple Reasons: (1) No configuration was supplied to the operation. (2) No input document was specified in the configuration. (3) The page number you specified is either below 0 or exceeds the document's total number of pages. (4) The supplied configuration was not valid for some reason. See the error message for details. (5) The version of the client that was used is outdated and no longer supported. This is only available for the PDFreactor REST clients.

401

The client failed an authorization check, e.g. because a supplied API key was invalid.

422

The supplied configuration was accepted by PDFreactor but could not be converted for some reason. See the error message for details.

500

Multiple Reasons: (1) The configuration could not be processed and should be re-checked. (2) The supplied configuration is valid, however the conversion could not be completed for some reason. See the error message for details.

503

Multiple Reasons: (1) Asynchronous conversions are not available in this PDFreactor Web Service. (2) The PDFreactor Web Service is running and reachable, but not in a state to perform the requested task.

Request samples

Content type
Copy
Expand all Collapse all
{
  • "addAttachments": true,
  • "addBookmarks": true,
  • "addComments": true,
  • "addLinks": true,
  • "addOverprint": true,
  • "addPreviewImages": true,
  • "addTags": true,
  • "allowAnnotations": true,
  • "allowAssembly": true,
  • "allowCopy": true,
  • "allowDegradedPrinting": true,
  • "allowFillIn": true,
  • "allowModifyContents": true,
  • "allowPrinting": true,
  • "allowScreenReaders": true,
  • "appendLog": true,
  • "attachments":
    [
    ],
  • "authenticationCredentials":
    {
    },
  • "author": "string",
  • "baseURL": "string",
  • "baseUrl": "string",
  • "bookletMode":
    {
    },
  • "callbacks":
    [
    ],
  • "cleanupTool": "CYBERNEKO",
  • "colorSpaceSettings":
    {
    },
  • "conformance": "PDF",
  • "contentObserver":
    {
    },
  • "continuousOutput":
    {
    },
  • "conversionName": "string",
  • "conversionTimeout": 0,
  • "cookies":
    [
    ],
  • "creator": "string",
  • "cssSettings":
    {
    },
  • "customDocumentProperties":
    [
    ],
  • "debugSettings":
    {
    },
  • "defaultColorSpace": "CMYK",
  • "disableBookmarks": true,
  • "disableFontEmbedding": true,
  • "disableLinks": true,
  • "document": "string",
  • "documentDefaultLanguage": "string",
  • "documentType": "AUTODETECT",
  • "enableDebugMode": true,
  • "encoding": "string",
  • "encryption": "NONE",
  • "errorPolicies":
    [
    ],
  • "fontAliases":
    [
    ],
  • "fontFallback":
    [
    ],
  • "fonts":
    [
    ],
  • "forceGrayscaleImage": true,
  • "fullCompression": true,
  • "httpsMode": "LENIENT",
  • "ignoreAlpha": true,
  • "inspectableSettings":
    {
    },
  • "integrationStyleSheets":
    [
    ],
  • "javaScriptMode": "DISABLED",
  • "javaScriptSettings":
    {
    },
  • "keepDocument": true,
  • "keywords": "string",
  • "licenseKey": "string",
  • "logExceedingContent":
    {
    },
  • "logLevel": "DEBUG",
  • "logMaxLines": 0,
  • "mediaFeatureValues":
    [
    ],
  • "mediaTypes":
    [
    ],
  • "mergeByteArray": "string",
  • "mergeByteArrays":
    [
    ],
  • "mergeDocuments":
    [
    ],
  • "mergeMode": "APPEND",
  • "mergeURL": "string",
  • "mergeURLs":
    [
    ],
  • "outputFormat":
    {
    },
  • "outputIntent":
    {
    },
  • "overlayRepeat": "ALL_PAGES",
  • "ownerPassword": "string",
  • "pageOrder": "BOOKLET",
  • "pagesPerSheetProperties":
    {
    },
  • "pdfScriptAction":
    [
    ],
  • "pixelsPerInch": 0,
  • "pixelsPerInchShrinkToFit": true,
  • "postTransformationDocumentType": "AUTODETECT",
  • "printDialogPrompt": true,
  • "processingPreferences":
    [
    ],
  • "quirksSettings":
    {
    },
  • "rawCookies":
    [
    ],
  • "requestHeaders":
    [
    ],
  • "requestPriority": 0,
  • "resourceConnectTimeout": 0,
  • "resourceReadTimeout": 0,
  • "resourceRequestTimeout": 0,
  • "segmentationSettings":
    {
    },
  • "signPDF":
    {
    },
  • "subject": "string",
  • "throwLicenseExceptions": true,
  • "title": "string",
  • "urlRewriteSettings":
    {
    },
  • "userPassword": "string",
  • "userScripts":
    [
    ],
  • "userStyleSheets":
    [
    ],
  • "validateConformance": true,
  • "viewerPreferences":
    [
    ],
  • "xmp":
    {
    },
  • "xsltMode": true,
  • "xsltStyleSheets":
    [
    ]
}

Response samples

Content type
Copy
Expand all Collapse all
{
  • "callbackUrl": "string",
  • "connections":
    [
    ],
  • "contentType": "string",
  • "conversionName": "string",
  • "document": "string",
  • "documentArray":
    [
    ],
  • "documentId": "string",
  • "documentUrl": "string",
  • "documentUrls":
    [
    ],
  • "endDate": "2021-09-24T13:25:27Z",
  • "error": "string",
  • "exceedingContents":
    [
    ],
  • "javaScriptExports": "string",
  • "keepDocument": true,
  • "log":
    {