1. Overview

The PDF Stamper API enables the possibility to add both static and dynamic stamps on existing PDFs. The stamps can consist of one or more barcode, hyperlink, image, line or text elements.

The flow is generally as follows:
1. Make a configuration containing the stamp information
2. Create a job specifying the desired configuration
3. Add one or more PDF files to the job
4. Start the job for processing
5. Retrieve the processed files

Full API Documentation: https://docs.sphereon.com/api/pdf-stamper/0.2
Interactive testing: A web based test console is available in the Sphereon API Store at https://store.sphereon.com

1.1. Version information

Version : 0.2

1.2. Contact information

Contact : Sphereon DevOps Team
Contact Email : dev@sphereon.com

1.3. License information

License : Apache License Version 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0
Terms of service : https://docs.sphereon.com/api/pdf-stamper/0.2

1.4. URI scheme

Host : gw.api.cloud.sphereon.com
BasePath : /pdf/stamp/0.2
Schemes : HTTPS

1.5. Tags

  • Config : API for PDF stamper configuration

  • Jobs : PDF stamper job related API’s

2. Introduction

The Sphereon PDF Stamper API provides a solution to stamps elements on existing PDF documents. The stamps can consist of one or more barcode, hyperlink, image, line or text elements. A configuration describing the stamp can be applied on a PDF document.

2.1. Integration with other API’s (file access)

Almost all of our Content API’s have uniform content access, meaning the storage API is the base for all content retrieval, manipulation and storage.

We provide you with 2 ways to interact with files and content in this PDF stamp API.

2.1.1. Content manipulation from Content API itself

This API has it’s own content upload and download endpoints. Files are stored in our cloud, or on one your own storage locations. Behind the scenes we use our storage API’s. This allows for simple integrations on your behalf. Our PDF Stamp API has simple multipart file upload capability for to be converted files, as wel as download capability for the result(s). So only a single location for storage is supported using this option.

2.1.2. Pass in storage locations to the Content API

You can use our Storage API (0.8) directly to upload, download and delete content. The Storage API will provide you with Json objects for the storage location(s). You use these locations for initiating the PDF stamping actions.
This solution has the benefit that you don’t have to upload a file to our stamp API beforehand. We will retrieve the file when necessary. It also means you can have several different storage locations, and even different cloud providers at the same time.

All our API’s will always return information about stream and storage locations. This allows you to mix and match both approaches as you see fit.
== SDKs

Our API’s are based on the OpenAPI specification (formerly known as Swagger specification). This means you can pickup our REST API definition file and generate classes for your favorite programming language.

2.2. Provided SDKs and generated SDKs

2.2.1. Provided SDKs

For some popular programming languages we provide you with an SDK implementation.
This implementation can be found at https://github.com/Sphereon-SDK/pdf-stamper-sdk

2.2.2. Generate your own SDK

Please feel free to generate an SDK for your own programming language using our Swagger file. Please note that we do not officially support your SDK, but unofficially we are here to help of course.
You can use Swagger codegen for this (https://swagger.io/swagger-codegen). Swagger codegen support almost 100 programming languages.

Please use version 2.X of swagger codegen with our current API’s

2.3. Version compatibility between SDK and API

Al of our REST API’s follow the versioning scheme below

XX.YY

When the major number (XX) changes this means we completely redesign an API.
Minor number (YY) changes means smaller backwards compatible breaks within the API. An API can be changed forward compatible within the same minor number.

Our SDK follow the below versioning scheme

XX.YY.ZZ

The major (XX) and minor (YY) number always map directly to the accompanying REST API version.
The micro number (ZZ) is used if we add forward compatible changes to our REST API, or when bugs are encountered in a specific SDK.

3. Privacy and file storage

This API uses the Sphereon Storage API to store or retrieve files.
Both input- and output files can be stored or retrieved using our Storage API.
Our Storage API provides integration with Amazon S3 ®, Google Cloud Storage ®, Xillio Engine or our Sphereon Storage.
Therefore you have the flexibility to store your files at a place you want.
More information about the Storage API: https://docs.sphereon.com/api/storage/0.8/html

You don’t have to configure the storage API if you want to rely on Sphereon to do the storage for you.
You do however need to be subscribed to the storage API from within your application and environment.

4. About Files

4.1. Lifecycle of a file

Lifecycle specifies if a file must or must not be deleted after retrieval. If you use cloud storage you might want to keep files.
If the lifecycle isn’t provided or the action is set to "NONE", files will not be deleted.

Lifecycles apply to input files/streamlocations, result files/streamlocations and the job itself. You can configure them separately.
Please note that when you specify a date/time for cleanup, the file might not be deleted at exactly the time, as the cleanup task
runs in the background, and only guarantees the job and/or files are not cleaned-up before the specified time.

When you specify a TIME type, there will be no delete on retrieval. if you do not provide a specific date/time the deletion
will happen one day from the job creation.

Currently you cannot have both delete on retrieval and/or time, whichever comes first.

4.2. Storage location

A storage location specifies the base location on a specific backend, e.g. Amazon.
The storage location allows you to define where to place result files. In some cases you might want to overwrite source files with the stamped version. Typically in a cloud environment you see this requirement. In that case you will have to set the storageMode in the ResultSettings to REPLACE_INPUT.

4.3. Stream location

A stream location specifies the location of a file on a specific backend. Even if you upload multipart files for stamping yourself the API will return stream locations in it’s responses.
You can also work with streamlocations as inputs for the stamping if you have existing (cloud) files on for instance Amazon, Google, Azure. A prerequisite for this approach is a configured Storage API in the same application.

5. Specifications

5.1. Supported input formats

The PDF Stamper API requires a PDF as input. If you have a file that is not in PDF format, you can use our PDF API first
to convert files to PDF.

The following input formats can be used for image resource in the configuration:

  • Image files: JPEG, TIFF, BMP, GIF, or PNG

These files can be stored on cloud locations using our Storage API if you want (see storage chapters).

6. Workflow

6.1. Stamp a PDF document

In order to create a stamp on a document, the following steps have to be taken.

6.1.1. Create a configuration

First create a configuration. The configuration contains the information about the stamp. The configuration can be reused for multiple jobs. Alternatively, configuration can be given directly to the job without the ability to reuse the configuration.
The configuration allows users to define variables that will be replaced when stamping the PDF. Placeholders will be replaced by these variables. Placeholders can be used in barcode content, hyperlink addresses and text components.

The following stamp elements are available:

For more technical info also see Create PDF stamper configuration

Note 1: A [HyperLinkComponent] is a transparent overlay. Meaning it will create a box you can overlay onto text. Any URL will not
be visible in the result PDF. The transparent box brings you to the provided URL, once you click the location in the PDF document.
So typically you want to create an Image, Barcode or text first and then at the same location create a hyperlink component.

The PDF Stamp API can work with variables, which are defined per job and are globally replaced in hyperlinks, texts and barcodes.
Additionally the PDF Stamp API can work with PDF forms. In order to fill in form fields, you will have to provide the fields in the
stamp configuration. When fields are provided that are not available in the form an error will occur.

Note 2: When using TextComponents and multiple lines, we suggest to use multiple components, for precise placement of the text.
Having said that, common linebreak characters like \r\n and \n and unicode variants are supported. Although you can provide a linespacing value, automatic newlines do mean some assumptions will be made.

6.1.2. Create a job

Create a PDF Stamper job. A configuration should be set in the job settings. This can be done by attaching one or more existing configuration ids or by adding a configuration inline within the job settings. The stamp settings can be changed when submitting the job.

The following stamp settings are available:

  • A list of configuration ids. The id correspond to the configuration id created in advance. Each configuration will be used to create a stamp and overlay this on the documents.

  • A inline Configuration that is used only once for the specific created job.

  • Variables that can be used to fill placeholders in the components. Placeholders can be used in barcode content, hyperlink addresses and text components. For example, if a text component contains the text "from: ${company}" and the variables contain a key-value pair "company: Sphereon", the text that will be stamped is "from: Sphereon".
    Don’t confuse variable with fields. Variables will always be replaced in hyperlinks, texts and QR codes. Fields can only be set
    on the Stamper Configuration itself and are only applicable to PDF forms.

  • Input settings in which the location and lifecycle can be set for input documents. The documents that will be uploaded will be placed in the storage location.

  • Result settings in which the location and lifecycle can be set for result documents.

  • Lifecycle settings of the job, input and output documents.

For more technical info also see Create PDF stamper job

6.1.3. Upload one or multiple files or attach one or more input locations to the job

After the creation of a job the obtained jobId in PdfStamperConfigContainer must be used to link files or input locations to the job.

Three options are available
* One can directly upload a file with Upload a file.
* Upload a file with Upload a base64 encoded file. This allows to upload the in file in a JSON structure. The file is Base64 encoded.
* A StreamLocation that is provided by Sphereon Storage API. This allows the file to be remotely stored and/or retrieved using for instance Amazon S3 storage, or Azure blob storage.

6.1.4. Submit the job

After one or more input files or StreamLocations were added to the job, the job can be submitted for processing.
If not specified at job creation, stamp settings can also be specified inline.
After submitting the job, the PDF Stamper API will asynchronously process the request. So you will not get back the result immediately.

For more technical info also see Submit PDF stamper job for processing.

6.1.5. Check by polling the job if the job is completed

Please repeatedly poll the job definition and state in order to check if the job is finished.
To reduce system load, allow one or more seconds waiting time between two polls. If the job state is ERROR, it will not recover at a later point in time.

For more technical info also see Job definition and state

6.1.6. Get the resulting file

After job completion the resulting file can be retrieved.
If the StorageLocation in ResultSettings which is in PdfStamperConfigContainer is specified, the result will be at that StorageLocation.

For more technical info also see Get the current result stream

6.1.7. Delete the job

After the result file has been collected, the job can be deleted. The job settings, Input and/or Result files will be deleted depending on the Lifecycle settings.

For more technical info also see Delete a job manually.

6.2. Other functions

6.2.1. Get all your jobs

This job provides a list of jobs at a specified state. This list can be used to delete jobs batchwise for instance.
Or it can be used to check the state of multiple simultaneously submitted jobs.

For more technical info also see Get all jobs.

7. Resources

7.1. Config

API for PDF stamper configuration

7.1.1. Create PDF stamper configuration

POST /config
Description

Create / initialize a new PDF stamper configuration.

Parameters
Type Name Description Schema

Body

pdfStamperConfiguration
required

The PDF stamper configuration

PdfStamperConfig

Responses
HTTP Code Description Schema

201

PDF Stamp configuration has been successfully created.

PdfStamperConfigContainer

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.1.2. Get PDF stamper configuration

GET /config/{configId}
Description

Retrieve a PDF stamper configuration.

Parameters
Type Name Description Schema

Path

configId
required

The PDF stamper configuration id

string

Responses
HTTP Code Description Schema

200

A PdfStamperConfigContainer object

PdfStamperConfigContainer

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.1.3. Update PDF stamper configuration

PUT /config/{configId}
Description

Update an existing PDF stamper configuration.

Parameters
Type Name Description Schema

Path

configId
required

The PDF stamper configuration id

string

Body

pdfStamperConfiguration
required

The PDF stamper configuration

PdfStamperConfig

Responses
HTTP Code Description Schema

200

A PdfStamperConfigContainer object

PdfStamperConfigContainer

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.1.4. Delete PDF stamper configuration

DELETE /config/{configId}
Description

Delete a PDF stamper configuration.

Parameters
Type Name Description Schema

Path

configId
required

The PDF stamper configuration id

string

Responses
HTTP Code Description Schema

200

A PdfStamperConfigContainer object

PdfStamperConfigContainer

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.1.5. Delete resources

DELETE /config/{configId}/streams
Description

Delete resources referenced by a configuration.

Parameters
Type Name Description Schema

Path

configId
required

The PDF stamper configuration id

string

Body

streamLocations
required

The resource locations in storage

< StreamLocation > array

Responses
HTTP Code Description Schema

200

The resources were deleted successfully

No Content

Security
Type Name Scopes

oauth2

oauth2schema

global

7.1.6. Upload resource

POST /config/{configId}/streams/multipart
Description

Upload a resource needed by a configuration.

Parameters
Type Name Description Schema

Path

configId
required

configId

string

FormData

stream
required

The resource data

file

Responses
HTTP Code Description Schema

200

A StreamLocation object

StreamLocation

Consumes
  • multipart/form-data

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.2. Jobs

PDF stamper job related API’s

7.2.1. Create PDF stamper job

POST /jobs
Description

Create a job using the given settings.

Parameters
Type Name Description Schema

Body

jobSettings
required

jobSettings

PdfStamperJobSettings

Responses
HTTP Code Description Schema

201

PDF stamper job created but not started yet

PdfStamperJobContainer

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.2.2. Get all jobs

GET /jobs
Description

Get all PDF stamper job definitions and their current state.

Parameters
Type Name Description Schema

Query

jobStatuses
optional

A list of jobStatuses to filter on.

< enum (CREATED, INPUTS_UPLOADED, PROCESSING, DONE, ERROR, DELETED) > array(multi)

Responses
HTTP Code Description Schema

200

All PDF jobs that have not been deleted

< PdfStamperJobContainer > array

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.2.3. Job definition and state

GET /jobs/{jobid}
Description

Get the PDF stamper job definition and current state. Please note that you can differentiate based on http response status.

Parameters
Type Name Description Schema

Path

jobid
required

jobid

string

Responses
HTTP Code Description Schema

200

PDF job returned and Job is done or in error

PdfStamperJobContainer

202

PDF job returned and Job is still processing

PdfStamperJobContainer

404

Invalid job id

ErrorResponse

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.2.4. Submit PDF stamper job for processing

PUT /jobs/{jobid}
Description

Start PDF stamper job for processing. Stamp one or more configurations on the previously uploaded PDFs. If the optional settings are supplied with the job in the request body, they are being used, otherwise the settings created during job creation are being used. You can only submit the job after a new Job is created with status INPUTS_UPLOADED or resubmit an existing Job with status ERROR.

Parameters
Type Name Description Schema

Path

jobid
required

jobid

string

Body

job
optional

jobSettings

PdfStamperJobSettings

Responses
HTTP Code Description Schema

200

Conversion job submitted

PdfStamperJobContainer

400

Resubmitted job not allowed because the job is currently processing or already processed and had status DONE

ErrorResponse

404

Invalid job id

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.2.5. Delete a job manually

DELETE /jobs/{jobid}
Description

Delete the PDF stamper job and all related files depending on the lifecycle.

Parameters
Type Name Description Schema

Path

jobid
required

jobid

string

Responses
HTTP Code Description Schema

200

PDF job returned and Job is done or in error

PdfStamperJobContainer

400

Could not delete all parts

ErrorResponse

404

Invalid job id

ErrorResponse

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.2.6. Upload a base64 encoded file

POST /jobs/{jobid}/streams/content
Description

Upload an image, office or pdf for conversion to PDF, embedded in a json as a base64 encoded string

Parameters
Type Name Description Schema

Path

jobid
required

jobid

string

Body

fileContent
required

File content

FileContentRequest

Responses
HTTP Code Description Schema

200

File content uploaded. The JSON Job response will be returned in the body.

PdfStamperJobContainer

400

Job could not be stored/processed

ErrorResponse

404

Invalid job id.

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.2.7. Add Input Stream Location(s)

POST /jobs/{jobid}/streams/location
Description

Add image, office or pdf input stream location(s) from the storage API for conversion to PDF. Please note that you can upload multiple files. Conversion will not be started yet.

Parameters
Type Name Description Schema

Path

jobid
required

jobid

string

Body

streamLocations
required

The (additional) binary image or PDF (file/inputstream) to convert to PDF

< StreamLocation > array

Responses
HTTP Code Description Schema

200

Stream location(s) added. The JSON Job response will be returned in the body.

PdfStamperJobContainer

400

Job could not be stored/processed

ErrorResponse

404

Invalid job id.

ErrorResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.2.8. Upload a file

POST /jobs/{jobid}/streams/multipart
Description

Upload a pdf to stamp one or more configurations. Please note that you can upload multiple files.

Parameters
Type Name Description Schema

Path

jobid
required

jobid

string

FormData

stream
required

The (additional) binary image or PDF (file/inputstream) to convert to PDF

file

Responses
HTTP Code Description Schema

200

File uploaded. The JSON Job response will be returned in the body.

PdfStamperJobContainer

400

Job could not be stored/processed

ErrorResponse

404

Invalid job id.

ErrorResponse

Consumes
  • multipart/form-data

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

7.2.9. Get the current result stream

GET /jobs/{jobid}/streams/result
Description

Get the PDF stamper as binary stream/file.
Our API generation does not allow changing the media type based on the Accepted header unfortunately.
This means we use a separate path postfix with the value '/stream'.
This API only returns the PDF when the response status is DONE.

Parameters
Type Name Description Schema

Path

jobid
required

jobid

string

Responses
HTTP Code Description Schema

200

PDF successfully created and returned

string (byte)

202

PDF not yet created. Job is still executing. Will return the JSON job instead of the PDF

integer (int32)

400

PDF could not be created.

ErrorResponse

404

Invalid job id. No response body is supplied

ErrorResponse

Produces
  • application/octet-stream

  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

8. Security

8.1. oauth2schema

Type : oauth2
Flow : application
Token URL : https://gw.api.cloud.sphereon.com/token

Name Description

global

accessEverything

9. Definitions

9.1. BarcodeComponent

A barcode component to stamp a barcode on a pdf

Polymorphism : Inheritance
Discriminator : type

Name Description Schema

barcodeFormat
required

The barcode format to generate

enum (AZTEC, CODABAR, CODE_39, CODE_93, CODE_128, DATA_MATRIX, EAN_8, EAN_13, ITF, MAXICODE, PDF_417, QR_CODE, RSS_14, RSS_EXPANDED, UPC_A, UPC_E, UPC_EAN_EXTENSION)

border
optional

The border of the component

Border

connectors
optional

Connectors containing components that can be positioned relative to this component

< Connector > array

content
required

The contents to encode in the barcode

string

errorCorrectionLevel
optional

Specifies what degree of error correction to use, for example in QR Codes, See ISO 18004:2006, 6.5.1. This enum encapsulates the four error correction levels defined by the QR code standard

enum (QR_L, QR_M, QR_Q, QR_H)

height
required

The preferred height in pixels

integer (int32)

offset
optional

The offset of the component relative to the parent component

Point

qrVersion
optional

integer (int32)

type
required

The discriminator type for serialization of the different components

string

width
required

The preferred width in pixels

integer (int32)

9.2. BlockchainConfig

The optional Blockchain configuration

Name Description Schema

blockchainAnchors
optional

The states at which to create a blockchain anchor. This can be the original file (before stamp)the stamped file, or both

< enum (BEFORE_STAMP, AFTER_STAMP) > array

proofConfigName
required

The blockchain proof configuration name to use

string

9.3. Border

Border of component

Name Description Schema

color
required

The color of the border

Color

thickness
optional

The thickness of the border line

number (float)

9.4. CanvasComponent

A canvas space interconnecting zones on the page to stamp components

Name Description Schema

border
optional

The border of the component

Border

connectors
optional

Connectors containing components that can be positioned relative to this component

< Connector > array

offset
optional

The offset of the component relative to the parent component

Point

pageOperation
required

The operation that should be executed with the stamp component

enum (STAMP)

pageSelector
required

Prescribes the page the component needs to be overlay-ed

enum (FIRST_PAGE, LAST_PAGE, EVEN_PAGES, ODD_PAGES, ALL_PAGES, SPECIFIC_PAGES)

specificPages
optional

< integer (int32) > array

type
required

The discriminator type for serialization of the different components

string

9.5. Color

A color object

Name Description Schema

name
optional

Use one of the common predefined colors

enum (BLACK, WHITE, RED, GREEN, BLUE, YELLOW, CYAN, MAGENTA, PINK, GRAY, DARK_GRAY, LIGHT_GRAY, ORANGE)

rgbValue
optional

Use a color that is composed out of the red, green and blue values

RGBValue

9.6. Connector

Connection between components containing anchor points and offset of the component

Name Description Schema

components
optional

< StampComponent > array

horizontalAnchorPoint
required

The horizontal anchor point to which the components are connected

enum (LEFT, CENTER, RIGHT)

offset
optional

The offset op the components relative to the parent component

Point

verticalAnchorPoint
required

The vertical anchor point to which the components are connected

enum (TOP, MIDDLE, BOTTOM)

9.7. DefaultJobSettings

Default PDF Stamper job settings

Name Description Schema

inputSettings
optional

The default input file and lifecycle settings

InputSettings

resultSettings
optional

The default result file and lifecycle settings

ResultSettings

variables
optional

A map with key-values used to replace template variables in components. These are optional defaults. Values in job specific variables will overwrite default values.

< string, string > map

9.8. Dimension

Dimension

Name Schema

height
required

number (float)

unit
optional

enum (pt)

width
required

number (float)

9.9. Error

An error

Name Schema

cause
optional

Error

code
required

string

level
required

enum (INFO, WARNING, FATAL)

message
required

string

9.10. ErrorResponse

The error response

Name Schema

errors
optional

< Error > array

9.11. FileContentRequest

Filecontent request

Name Description Schema

content
required

The file as a base64 encoded string

string

contentType
required

Content type

string

fileName
required

Original filename

string

9.12. HyperlinkComponent

An hyperlink component to stamp a hyperlink on a pdf

Polymorphism : Inheritance
Discriminator : type

Name Description Schema

address
required

The hyperlink address

string

border
optional

The border of the component

Border

connectors
optional

Connectors containing components that can be positioned relative to this component

< Connector > array

height
required

The preferred height in pixels

integer (int32)

offset
optional

The offset of the component relative to the parent component

Point

type
required

The discriminator type for serialization of the different components

string

width
required

The preferred width in pixels

integer (int32)

9.13. ImageComponent

An image component to stamp an image on a pdf

Polymorphism : Inheritance
Discriminator : type

Name Description Schema

border
optional

The border of the component

Border

connectors
optional

Connectors containing components that can be positioned relative to this component

< Connector > array

imageData
optional

The image as a base64 string

string

imageStreamLocation
optional

The stream location of the image. This is used if image data hasn’t been set

StreamLocation

offset
optional

The offset of the component relative to the parent component

Point

scaledDimension
optional

The preferred dimension of the image

Dimension

type
required

The discriminator type for serialization of the different components

string

9.14. InputResources

Input response

Name Description Schema

streamLocations
optional

Input Stream Locations

< StreamLocation > array

9.15. InputSettings

Input settings. Specify, if applicable, external location of the inputfile(s)

Name Description Schema

lifecycle
optional

The lifecycle of input files

Lifecycle

storageLocation
optional

Input Storage location. This is where input files will be stored when addInput is called

StorageLocation

9.16. Lifecycle

Lifecycle settings. When no lifecycle settings are supplied, the job and files will be deleted directly after retrieval of the file

Name Description Schema

action
optional

The action to perform. Currently only delete is supported

enum (DELETE, NONE)

actionTime
optional

The time at which the job and files will be deleted, regardless of whether it has been retrieved or not. Maximal time is 1 day from job creation

string (date-time)

applicableJobStatusses
optional

Job status needs to be in this list in order for the action to be performed!

< enum (CREATED, INPUTS_UPLOADED, PROCESSING, DONE, ERROR, DELETED) > array

type
optional

Determine when to delete the job and associated files.
RETRIEVAL means delete directly after retrieving the PDF file. When the file has not been retrieved before the action time, it will be deleted regardless.
Time means, delete on specific time, regardless of whether it has been processed

enum (RETRIEVAL, TIME)

9.17. LineComponent

A line component to stamp a line on a pdf

Polymorphism : Inheritance
Discriminator : type

Name Description Schema

border
optional

The border of the component

Border

color
optional

The color of the line

Color

connectors
optional

Connectors containing components that can be positioned relative to this component

< Connector > array

lineTo
required

The point to which the line should be drawn

Point

lineWidth
optional

The thickness of the line

number (float)

offset
optional

The offset of the component relative to the parent component

Point

type
required

The discriminator type for serialization of the different components

string

9.18. PdfStamperConfig

The PDF stamper configuration

Name Description Schema

blockchainConfig
optional

Optional blockchain proof configuration

BlockchainConfig

canvasComponents
optional

The canvas components containing the information of the stamp

< CanvasComponent > array

defaultJobSettings
optional

Default job settings. Values omitted from the job will follow default settings specified in here

DefaultJobSettings

fields
optional

The form fields that should be filled

< string, string > map

storageLocation
optional

The storage location where the configuration resources will be stored

StorageLocation

9.19. PdfStamperConfigContainer

Container with the PDF stamper configuration

Name Description Schema

configId
required
read-only

The configuration id

string

configStatus
optional
read-only

The status of the configStatus action

enum (CREATED, UPDATED, RESOURCE_UPLOADED, ERROR, DELETED, DONE)

creationTime
optional
read-only

The creation date/time of the initial configuration in ISO 8601 format

string (date-time)

name
optional

An optional configuration name

string

pdfStamperConfig
required

The PDF stamper configuration

PdfStamperConfig

registeredResources
optional

< StreamLocation > array

statusMessage
optional
read-only

A status message, which can be informational, warning or error. A message here does not indicate an error per se

string

updateTime
optional
read-only

The last update date/time of this configuration in ISO 8601 format

string (date-time)

9.20. PdfStamperJobContainer

The PDF Stamper job.

Name Description Schema

completionTime
optional
read-only

The completion date/time of this job in ISO 8601 format

string (date-time)

creationTime
optional
read-only

The creation date/time of this job in ISO 8601 format

string (date-time)

input
optional

The input(s)

InputResources

jobId
optional
read-only

The job id

string

jobStatus
optional
read-only

The status of the job

enum (CREATED, INPUTS_UPLOADED, PROCESSING, DONE, ERROR, DELETED)

queueTime
optional
read-only

The PDF Stamper queue date/time of this job in ISO 8601 format

string (date-time)

result
optional

The result(s)

ResultResources

settings
optional

The settings used during executing the PDF Stamper job

PdfStamperJobSettings

statusMessage
optional
read-only

A status message, which can be informational, warning or error. AA message here does not indicate an error per se

string

updateTime
optional
read-only

The last update date/time of this job in ISO 8601 format

string (date-time)

9.21. PdfStamperJobSettings

PDF stamper job settings

Name Description Schema

configuration
optional

A configuration that only applies for one job without the ability to be reused.

PdfStamperConfig

inputSettings
optional

The input file and lifecycle settings

InputSettings

jobLifecycle
optional

The lifecycle of the job itself

Lifecycle

resultSettings
optional

The result file and lifecycle settings

ResultSettings

useConfiguration
optional

A list of configuration ids that have to be applied during executing the job.

< string > array

variables
optional

A map with key-values used to replace template variables in components.

< string, string > map

9.22. Point

Location point

Name Schema

unit
optional

enum (pt)

x
required

number (float)

y
required

number (float)

9.23. RGBValue

A RGB color value

Name Schema

b
required

integer (int32)

g
required

integer (int32)

r
required

integer (int32)

9.24. ResultResources

Result response

Name Description Schema

streamLocations
optional

Result Stream Locations

< StreamLocation > array

9.25. ResultSettings

Result settings

Name Description Schema

lifecycle
optional

The lifecycle of result files

Lifecycle

storageLocation
optional

Result Storage location

StorageLocation

storageMode
optional

Storage mode. Can be a configured storage location on the storage API, a job id folder in the supplied storage location or completely replacing the input files (streamlocations).

enum (STORAGE_LOCATION, STORAGE_LOCATION_JOB_IDS, REPLACE_INPUT)

9.26. StampComponent

Name Description Schema

border
optional

The border of the component

Border

connectors
optional

Connectors containing components that can be positioned relative to this component

< Connector > array

offset
optional

The offset of the component relative to the parent component

Point

type
required

The discriminator type for serialization of the different components

string

9.27. StorageLocation

Storage Location

Name Schema

containerId
optional

string

folderPath
optional

string

id
optional
read-only

string

9.28. StreamLocation

Location record of data stream

Name Schema

containerId
optional

string

filename
optional

string

folderPath
optional

string

id
optional
read-only

string

originalFilename
optional

string

9.29. TextComponent

An text component to stamp text on a pdf

Polymorphism : Inheritance
Discriminator : type

Name Description Schema

border
optional

The border of the component

Border

connectors
optional

Connectors containing components that can be positioned relative to this component

< Connector > array

fontName
optional

The font of the text

string

fontSize
optional

The size of the text

number (float)

lineSpacing
optional

Linespacing ratio. The default is 0.5 (meaning half a line height). The spacing is only applicable to newlines within a single text component

number (float)

nonStrokingColor
optional

The color of the text

Color

offset
optional

The offset of the component relative to the parent component

Point

text
required

The text that will be displayed

string

type
required

The discriminator type for serialization of the different components

string