eStamp: Workflow instructions for signing and validating PDF documents

Content

This document describes the available workflow types of the eStamp REST API and explains step by step how PDF documents are signed, sealed, and validated. Prerequisite for all workflows: a valid eStamp base URL and a valid bearer token (see “eStamp: Structure, Use, and Authentication”).

Overview: What types of workflows are available?

The eStamp REST API offers two main workflow types for signing documents and a separate workflow for validation:

Synchronous workflow (single request): A single API call immediately returns the signed document. Suitable for individual documents without temporary storage. Three variants available: sealSingle, sealSingleWithAppearance, sealSingleWithAppearanceParam.

Session-based workflow (batch): Multiple documents are processed within a single session. This involves several steps: startSession → addDocument → seal → getDocument → closeSession. Suitable for batch processing of up to 100 documents per session.

Validation workflow: Checks the signature of an existing PDF or XML document and returns a validation report.

[!NOTE] eStamp is not an asynchronous system. There are no background jobs, no status endpoints, no polling, and no webhooks. Each API call blocks until it is complete and returns the result directly.

Workflow 1: Synchronous signing (single request)

The synchronous signing workflow of the eStamp REST API processes a single document per API call and immediately returns the signed document as a binary file. There are no sessions, no caching, and no status to check.

Variant 1a: Signing without visualization (sealSingle)

Seals a PDF document without displaying a visual signature in the document.

# eStamp: Seal PDF without signature visualization
# Endpoint: POST /signApi/sealSingle
# Authentification: Bearer Token required
# Return: signed PDF as binary

curl -X POST "https://<base-url>/signApi/sealSingle" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: multipart/form-data" \
  -F "parameterId=<parameterId>" \
  -F "documentToSign=@./eingabe.pdf;type=application/pdf" \
  --output ./signiert.pdf

Parameter:

[!NOTE] documentToSign and file are synonymous field names with identical meanings. Both variants are accepted by the eStamp REST API.

Variant 1b: Signing with signature visualization as a file(sealSingleWithAppearance)

Seals a PDF document and inserts a visual signature representation at the configured position. The visualization configuration is passed as a JSON file.

# eStamp: Seal PDF with siganture visualization (Appearance as JSON file)
# Endpoint: POST /signApi/sealSingleWithAppearance
# Authentification: Bearer Token required
# Return: signed PDF with visualization as binary

curl -X POST "https://<base-url>/signApi/sealSingleWithAppearance" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: multipart/form-data" \
  -F "parameterId=<parameterId>" \
  -F "documentToSign=@./eingabe.pdf;type=application/pdf" \
  -F "signatureAppearance=@./appearance.json;type=application/json" \
  --output ./signiert.pdf

Example appearance.json (Required and optional fields):

{
  "signatureImageId": "amtsSignatur",
  "lastPage": -1,
  "onEveryPage": false,
  "x": 100,
  "y": 100,
  "width": 400,
  "height": 270,
  "signaturePageId": "default"
}

Variante 1c: Signieren mit Signaturvisualisierung als ID (sealSingleWithAppearanceParam)

Versiegelt ein PDF-Dokument mit einer serverseitig hinterlegten Visualisierungskonfiguration. Statt einer JSON-Datei wird nur die appearanceId als Query-Parameter übergeben. Die Konfiguration liegt serverseitig und muss nicht bei jedem Aufruf mitgesendet werden.

# eStamp: Seal PDF with signature visualization (appearance as server-side ID)
# Endpoint: POST /signApi/sealSingleWithAppearanceParam
# Authentification: Bearer Token required
# Return: signed PDF with visualization as binary

curl -X POST "https://<base-url>/signApi/sealSingleWithAppearanceParam?appearanceId=<appearanceId>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: multipart/form-data" \
  -F "parameterId=<parameterId>" \
  -F "file=@./eingabe.pdf;type=application/pdf" \
  --output ./signiert.pdf

Signature visualization(signatureAppearance): Configuration reference

The signatureAppearance-configuration controls how the signature is displayed visually in the PDF-position, size, signature image used, and page area. The configuration is always transferred in JSON format.

[!NOTE] The signatureAppearance-configuration is only relevant if the endpoints sealSingleWithAppearance or addDocumentWithAppearance are used. For sealSingle without vizalisation signatureAppearance is not necessary.

Mandatory fields of signatureAppearance

Optional fields of signatureAppearance

[!WARNING] signaturePageId and onEveryPage: true must not be set simultaneously. This combination leads to a 400 Bad Request-error.

Special case: Automatic positioning (visualizationAutomation)

visualizationAutomation automatically positions the signature visualization at the end of the last text character on the last page. Manual coordinate entry is not necessary.

{
  "signatureImageId": "amtsSignatur",
  "signaturePageId": "default",
  "x": 100,
  "width": 400,
  "height": 250,
  "visualizationAutomation": {
    "footerHeight": 6,
    "margin": 10,
    "signaturePageMargin": 60
  }
}

Required fields within visualizationAutomation:

[!WARNING] When using visualizationAutomation, two mandatory conditions apply: signaturePageId must be set to a valid value, and signatureAttributes must not be set. The combination of both special cases (visualizationAutomation and signatureAttributes) is not supported.

Special case: Placing a signature in an existing PDF signature field

If a PDF already contains signature fields, the visualization can be placed directly in an existing field. Coordinates, page information, and size are then not required.

{
  "signatureImageId": "imageOnly",
  "signatureFieldId": "Signatur2"
}

The following fields of signatureAppearance are not reqired when using signatureFieldId: firstPage, lastPage, onEveryPage, x, y, width, height.

To query the existing signature field IDs of a PDF document, use the following endpoint:

# eStamp: Query signature field IDs of a PDF
# Endpoint: POST /signApi/signatureFieldNames
# Rückgabe: JSON list of signature field IDs in the document

curl -X POST "https://<base-url>/signApi/signatureFieldNames" \
  -H "Authorization: Bearer <token>" \
  -F "document=@./eingabe.pdf;type=application/pdf"

Workflow 2: Session-based signing (batch)

The session-based signing workflow of the eStamp REST API processes multiple documents within a single session. The process involves several steps and must be carried out in the specified order.

Complete process:

POST /startSession
  → POST /{sessionId}/addDocument  (1–100 times)
  → POST /{sessionId}/seal
  → GET  /{sessionId}/getDocument/{documentId}  (for every document)
  → POST /{sessionId}/closeSession

[!WARNING] The order of the session steps must be strictly adhered to. A getDocument-call before seal returns a 404 Not Found error. AaddDocument-call after seal returns a 400 Bad Request error.

Step 1: Start session (startSession)

# eStamp: Start batch signing session
# Endpoint: POST /signApi/startSession
# Return: sessionId as JSON string

curl -X POST "https://<base-url>/signApi/startSession" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: multipart/form-data" \
  -F "parameterId=<parameterId>"

Successful response (200 OK):

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

The returned sessionId is required as a path parameter for all subsequent calls.

Step 2: Add documents (addDocument)

# eStamp: Add document to session
# Endpoint: POST /signApi/{sessionId}/addDocument
# Return: documentId as integer (JSON)
# This step is repeated for each document individually (max. 100 per session)

curl -X POST "https://<base-url>/signApi/<sessionId>/addDocument" \
  -H "Authorization: Bearer <token>" \
  -F "documentToSign=@./dokument1.pdf;type=application/pdf"

Successful response (200 OK):

1

The returned documentId is required in step 4 (getDocument) benötigt. Each added document is assigned its own documentId.

[!NOTE] Once added, documents cannot be replaced or removed within a session. If an incorrect document has been added, a new session must be started.

Alternatively, the following addDocument-variants are available:

Step 3: Seal all documents (seal)

# eStamp: Seal all documents in the session
# Endpoint: POST /signApi/{sessionId}/seal
# Return: no body (empty 200 response)
# Timeout: 60–120 seconds for the entire sealing process

curl -X POST "https://<base-url>/signApi/<sessionId>/seal" \
  -H "Authorization: Bearer <token>"

The seal-call blocks until all documents in the session are signed and does not return any content data. The signed documents are then retrieved using getDocument.

Step 4: Retrieve signed documents (getDocument)

# eStamp: Retrieve signed document from session
# Endpoint: GET /signApi/{sessionId}/getDocument/{documentId}
# Return: Signed PDF as binary
# This step is performed individually for each documentId

curl -X GET "https://<base-url>/signApi/<sessionId>/getDocument/<documentId>" \
  -H "Authorization: Bearer <token>" \
  --output ./signiert-dokument1.pdf

Step 5: Close session (closeSession)

# eStamp: Close batch signing session
# Endpoint: POST /signApi/{sessionId}/closeSession
# Return: no body

curl -X POST "https://<base-url>/signApi/<sessionId>/closeSession" \
  -H "Authorization: Bearer <token>"

[!NOTE] eStamp sessions that are not closed manually are automatically cleaned up after 40 minutes. A session that exceeds 40 minutes returns error 412 Precondition Failed (Illegal session id) on subsequent calls.

Workflow 3: Signature validation

The validation workflow of the eStamp REST API checks the signature of an existing PDF or XML document and returns a validation report.

Validate PDF signature

# eStamp: Validate PDF signature
# Endpoint: POST /signApi/validatePdf
# Parameter reportType: “xml” (default) or “pdf”
# Return: Validation report as XML or PDF binary

curl -X POST "https://<base-url>/signApi/validatePdf" \
  -H "Authorization: Bearer <token>" \
  -F "reportType=xml" \
  -F "file=@./signiert.pdf;type=application/pdf" \
  --output ./validierungsreport.xml

Validate XML signature

# eStamp: Validate XML signature
# Endpoint: POST /xmlSignApi/validateXml
# Parameter reportType: “xml” (default) or “pdf”
# Return: Validation report as XML or PDF binary

curl -X POST "https://<base-url>/xmlSignApi/validateXml" \
  -H "Authorization: Bearer <token>" \
  -F "reportType=pdf" \
  -F "file=@./signiert.xml" \
  --output ./validierungsreport.pdf

AvailablereportType-values:

FAQ: Workflows and frequently asked questions

What is the difference between synchronous and session-based workflows?

The synchronous workflow of the eStamp REST API processes a single document per API call and returns the result immediately — no sessions, no caching. The session-based workflow enables batch processing of up to 100 documents per session in a multi-step process. The synchronous workflow is simpler for individual documents; the session-based workflow is necessary for batch processing.

How many documents can be processed per session?

A maximum of 100 documents can be processed per eStamp batch session. If more than 100 documents need to be signed, multiple sessions must be started. There is no limit to the number of sessions that can run in parallel.

How long is an eStamp session valid?

An eStamp batch session is valid for 40 minutes from the startSessioncall. Sessions that are not completed are automatically cleared after 40 minutes. A single API call within a session may take a maximum of 30 seconds; if this time is exceeded, the call is canceled.

Can I check the progress of a running seal-call?

No. eStamp does not offer status endpoints, polling, or webhooks. The seal call blocks until all documents in the session are signed (maximum 60–120 seconds) and then returns an empty 200 response.

Can I remove documents from a session after adding them?

No. Once documents have been added to the session, they cannot be removed or replaced. If an incorrect document has been added, a new eStamp session must be started via startSession.

Is there partial failure in session processing?

No. eStamp does not support partial failure. A batch operation is either completely successful or completely fails. There is no partial processing of individual documents within a session.

What happens when a session expires or a timeout occurs?

When the 40-minute session validity expires, eStamp returns 412 Precondition Failed for subsequent calls. If a single API call times out (30 seconds), the call is canceled and an error message is returned. In both cases, no partial processing takes place. Expired sessions are automatically cleaned up.