POST /documentprocessing/pdf/create

POST https://example.com/documentprocessing/pdf/create

Description

Creates a PDF document from an input document.

Examples

The following example creates a new PDF document from a document in the internal format.

# Request:
curl --location --request POST 'https://trial.dsserver.io/documentprocessing/pdf/create?returnFormat=PDF' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer fePFHv8OtIyRSCAdOnn7USc9kKdYB2rg' \
    --data-raw '{
        "documentData": "eAUBAA4AAAAAAAAAAA[..]="
    }'

# Result:
"JVBERi0xLjQNJ[..]"

Authorization

This endpoint supports the OAuth authorization method. DS Server checks the access token only when OAuth is enabled in the admin portal (see Enable OAuth). With OAuth disabled, the default of a new installation, the endpoint accepts requests without a token.

DS Server implements OAuth as the authorization method. Two flows are supported:

Authorization Code
Client Credentials

To use the Client Credentials flow, switch on Allow “Client Credentials” grant type in the security profile (see OAuth Grant Types).

In both cases, a valid access token returned from the OAuth endpoints must be passed in a Bearer Authorization Header, as a Query Parameter or in a Cookie.

Authorization Header

Header field	Description
Authorization	A Bearer authorization header (also called token authentication) contains the OAuth access token. The authorization method and a space i.e. "Bearer " is then put before your valid access token. For example: `Authorization: Bearer 4796E23054E64BC773CACBCAF24AD179DE9A3`

Query Parameter

Query parameter	Description
access_token	The access token is passed directly in the endpoint URL as a query string. For example: `?access_token=4796E23054E64BC773CACBCAF24AD179DE9A3`

Cookie

Cookie	Description
access_token	The access token is passed in a cookie named `access_token`. For example: `Cookie: access_token=4796E23054E64BC773CACBCAF24AD179DE9A3`

Request Parameters

Name	Type	Value	Optional
returnFormat	String	A string that specifies the format of the created document. Possible values are: "PDF" and "PDFA" (PDF/A-3b). Default value is "PDF".	yes

Request Payload

Type	Value
PDFCreationSettings	The PDFCreationSettings object contains the settings for the requested PDF document.

PDFCreationSettings

Name	Type	Value	Optional
documentKeywords	String[]	String array that contains keywords that will be added to the PDF document meta information.	yes
documentLevelJavaScriptActions	String[]	String array that contains JavaScript actions that are embedded in the PDF.	yes
imageCompressionQuality	Integer	Specifies the compression quality of images, a value between 1 and 100.	yes
masterPassword	String	Specifies the password for the document's access permissions.	yes
digitalSignature	DigitalSignature	Specifies the digital signature that is used to sign the document.	yes
embeddedFiles	EmbeddedFile[]	Specifies an array of embedded files that are embedded into the document.	yes
documentAccessPermissions	DocumentAccessPermissions (Number)	Specifies access permissions for the document as the sum of the values below. It has an effect only if `masterPassword` is set. A name such as "AllowAll" is refused with 400.	yes
documentData	String	Document that will be converted to PDF encoded as Base64 string.	no
author	String	Sets the document's author.	yes
creationDate	DateTime (String)	Sets the document's creation date which will be saved in the document.	yes
lastModificationDate	DateTime (String)	Sets the date the document is last modified.	yes
creatorApplication	String	Sets the application, which has created the document.	yes
documentSubject	String	Sets the document's subject string which will be saved in the document. PDF limitation: The length is limited to 2000 characters.	yes
documentTitle	String	Sets the document's title that will be saved in the document. PDF limitation: The length is limited to 2000 characters.	yes
userPassword	String	Specifies the password for the user to open the document.	yes

DigitalSignature

Name	Type	Value	Optional
x509Certificate2	String	The X.509 certificate encoded as a Base64 string.	no
password	String	The password of the certificate.	no
timeServerURL	String	The URL of a time server.	yes

EmbeddedFile

Name	Type	Value	Optional
creationDate	DateTime (String)	Specifies the date of the creation.	yes
data	String	Specifies the data of the embedded file.	yes
dataType	String	Specifies the type of the data.	yes
description	String	Specifies the description of the embedded file.	yes
fileName	String	Specifies the file name of the embedded file.	yes
lastModificationDate	DateTime (String)	Specifies the last modification date.	yes
mimeType	String	Specifies the MIME type of the embedded file (for example: "application/pdf").	yes
relationship	String	Specifies the relationship string of the embedded file.	yes
metadata	String	Specifies meta data for the embedded file.	yes

DocumentAccessPermissions

Name	Type	Value	Optional
None = 0	Enum	Allows none of the possible permissions.	yes
AllowAuthoring = 1	Enum	Allows authoring comments and fill in interactive form fields (including signature fields).	yes
AllowAuthoringFields = 2	Enum	Fill-in existing interactive form fields (including signature fields) is allowed.	yes
AllowContentAccessibility = 4	Enum	Allows content access for the visually impaired only.	yes
AllowDocumentAssembly = 8	Enum	Allows to assemble the document (insert, rotate or delete pages and create bookmarks or thumbnails).	yes
AllowExtractContents = 16	Enum	Copying or otherwise extracting text and/or graphics is allowed.	yes
AllowGeneralEditing = 32	Enum	Allows modifying the document's contents.	yes
AllowHighLevelPrinting = 64	Enum	Printing the document is fully allowed.	yes
AllowLowLevelPrinting = 128	Enum	Printing the document is allowed (low-level).	yes
AllowAll = 255	Enum	Allows all of the possible permissions.	yes

Success Response

Status	Description
200	On success, the HTTP status code in the response header is 200 (OK). The response body contains the resulting document encoded as a Base64 encoded string.

Error Response

Status	Description
401	A 401 (Unauthorized) with an empty body is returned, if OAuth is enabled and the request has no valid access token.
400	A 400 (Bad Request) is returned, if the body can't be read as a PDFCreationSettings object. The body is a problem details object (`application/json`) with the title "One or more validation errors occurred." and the message per field in `errors`. This check comes before the license check.
415	A 415 (Unsupported Media Type) is returned, if the `Content-Type` header of a request with a body is not `application/json`.
405	A 405 (Method Not Allowed) with an empty body and the header `Allow: POST` is returned for any other HTTP method, for example `GET`.
400	A 400 (Bad Request) is returned, if DS Server is not licensed or the license is invalid. On a server that is not registered, the body is the JSON string `"DS Server is not registered."` (`application/json`). DS Server checks the license before the parameter values, but after it has read the body and the typed query parameters.
400	A 400 (Bad Request) is returned, if no data is found in the PDFCreationSettings object.
400	A 400 (Bad Request) is returned, if no documents were found in the PDFCreationSettings object.
400	A 400 (Bad Request) is returned, if the uploaded document is not valid.