eStamp: API-Referenz und Endpunkt-Katalog

Content

This document is the complete technical reference for all eStamp REST API endpoints. It describes the parameters, return values, and special features of each endpoint. Prerequisites for all calls: a valid, customer-specific eStamp base URL and a valid bearer token. All endpoints use the base path /signApi/... respectively /xmlSignApi/....

For an introduction to workflows and process logic, see “eStamp: Workflow instructions for signing and validating PDF documents.”

Configuration and Discovery

These eStamp endpoints provide information about the configuration of the current eStamp instance. They are the recommended starting point for any new integration.

GET /signApi/parameterInfos

Returns the list of all configured signature handlers for the eStamp instance. The parameterIdvalues from this response are mandatory parameters for all Seal endpoints.

Authentication: Bearer token required

# eStamp: Query available signature handlers
# Endpoint: GET /signApi/parameterInfos
# Return: JSON array of all configured signature handlers

curl -X GET "https://<base-url>/signApi/parameterInfos" \
  -H "Authorization: Bearer <token>"

Erfolgreiche Antwort (200 OK):

[
  {
    "parameterId": "amtssignatur",
    "displayName": "Amtssignatur",
    "maxNumberOfDocuments": 100,
    "signatureHandlerType": "SOFTWARE_KEY"
  }
]

Antwortfelder:

[!NOTE] The listed parameterId values are instance-specific. Only those parameters that are stored in the configuration of the eStamp instance are listed. Deprecated parameters are not marked separately.

GET /signApi/signatureAppearanceInfos

Returns the mapping of all server-side stored appearance IDs to their signatureAppearanceconfiguration. This endpoint is used to query available appearanceId values for the endpoints sealSingleWithAppearanceParam and addDocumentWithAppearanceParam endpoints.

Authentication: Bearer token required

# eStamp: Query available appearance configurations
# Endpoint: GET /signApi/signatureAppearanceInfos
# Return: JSON mapping of appearance IDs to signatureAppearance configurations

curl -X GET "https://<base-url>/signApi/signatureAppearanceInfos" \
  -H "Authorization: Bearer <token>"

[!NOTE] Server-side appearance configurations are stored in the eStamp instance as YAML and reference JSON configuration files. They are managed by the XiTrust support team during deployment.

Successful Response (200 OK):

json

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

GET /signApi/paraphenInfos

Returns the mapping of all server-side stored Paraphen IDs to their ParaphenAppearance configuration. This endpoint is used to query available paraphImageId and paraphenAppearanceId values.

Authentication: Bearer token required

# eStamp: Query available initials configurations
# Endpoint: GET /signApi/paraphenInfos
# Return: JSON mapping of initials IDs to ParaphenAppearance configurations

curl -X GET "https://<base-url>/signApi/paraphenInfos" \
  -H "Authorization: Bearer <token>"

Successful response (200 OK):

json

{
  "paraphen1": {
    "paraphImageId": "picture1",
    "x": 10,
    "y": 800,
    "width": 50,
    "height": 22
  },
  "paraphen2": {
    "paraphImageId": "picture2",
    "x": 20,
    "y": 750,
    "width": 50,
    "height": 22
  }
}

Synchronous Seal Endpoints (Single Document)

The synchronous eStamp Seal endpoints seal a single PDF document per call and return the signed document directly as a binary. No sessions are required.

POST /signApi/sealSingle

Seals a single PDF document without signature visualization (see Figure 1). The simplest eStamp seal endpoint.

Authentication: Bearer token required
Content-Type: multipart/form-data
Return: Signed PDF as binary (application/pdf); file name in response header

# eStamp: Seal PDF without visualization
# Endpoint: POST /signApi/sealSingle
# Return: Signed PDF as binary

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

Request-Parameter:

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

Successful Response (200 OK):

Sig_OhneVisualisierung.pdf

Figure 1: The result is a PDF document without a visual signature display (click on the file to view the result)

POST /signApi/sealSingleWithAppearance

Seals a single PDF document and inserts a visual signature representation. The signatureAppearance configuration is sent as a JSON file in the request.

Authentication: Bearer token required
Content-Type: multipart/form-data
Return: Signed PDF with visualization as binary (application/pdf)

#  eStamp: Seal PDF with signature visualization (appearance as JSON file)
# Endpoint: POST /signApi/sealSingleWithAppearance
# Return: Signed PDF with visualization as binary

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

Request-Parameter:

Successful Response (200 OK):

Sig_MitVisualisierung.pdf

Figure 2: The result is a PDF document with a visual representation of the signature (click on the file to view the result).

POST /signApi/sealSingleWithAppearanceParam

Seals a single PDF document with a visualization configuration stored on the server (see figure 3). Instead of a JSON file, the appearanceId is passed as a query parameter.

Authentication: Bearer token required
Content-Type: multipart/form-data
Return: Signed PDF with visualization as binary (application/pdf)

# eStamp: Seal PDF with server-side appearance ID
# Endpoint: POST /signApi/sealSingleWithAppearanceParam
# appearanceId: Query parameter (configured on the server side)
# Return: Signed PDF as binary

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

Request-Parameter:

Successful Response (200 OK):

Sig_MitVisualisierung.pdf

Sig_MitVisualisierung.pdf

Figure 3: The result is a PDF document with a visual representation of the signature (click on the file to view the result).

Session-based seal endpoints (batch)

The session-based eStamp endpoints process multiple documents in a multi-step session. The order of the calls must be strictly adhered to: startSession → addDocument → seal → getDocument → closeSession.

POST /signApi/startSession

Starts a new eStamp batch signing session and returns the sessionId which is used as a path parameter in all subsequent calls.

Authentication: Bearer token required
Content-Type: multipart/form-data
Return: sessionId as JSON-String

# 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>" \
  -F "parameterId=amtssignatur"

Successful Response (200 OK):

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Request-Parameter:

Fehlercodes:

POST /signApi/{sessionId}/addDocument

FAdds a document to the existing eStamp session. Returns a documentId that is required for getDocument. Can be called up to 100 times per session.

Authentication: Bearer token required
Content-Type: multipart/form-data
Return: documentId as integer (JSON)

# eStamp: Add document to session
# Endpoint: POST /signApi/{sessionId}/addDocument
# Return: documentId as integer

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

Successful Response (200 OK):

1

Request-Parameter:

Error codes:

[!NOTE] Documents added to a session cannot be removed or replaced. If a document is added incorrectly, a new session must be started via POST /signApi/startSession.

POST /signApi/{sessionId}/addDocumentWithAppearance

Adds a document with a signatureAppearance configuration to the eStamp session. The visualization configuration is passed as a JSON file.

Authentication: Bearer token required
Content-Type: multipart/form-data
Return: documentId as integer (JSON)

# eStamp: Add document with appearance configuration to session
# Endpoint: POST /signApi/{sessionId}/addDocumentWithAppearance

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

Request-Parameter:

Successful Response (200 OK):

json

2

POST /signApi/{sessionId}/addDocumentWithAppearanceParam

Adds a document with a server-side stored appearance ID to the eStamp session.

Authentication: Bearer token required
Content-Type: multipart/form-data
Return: documentId as integer (JSON)

# eStamp: Add document with server-side appearance ID to session
# Endpoint: POST /signApi/{sessionId}/addDocumentWithAppearanceParam

curl -X POST "https://<base-url>/signApi/<sessionId>/addDocumentWithAppearanceParam?appearanceId=<appearanceId>" \
  -H "Authorization: Bearer <token>" \
  -F "file=@./dokument.pdf;type=application/pdf"

Request-Parameter:

Error codes:

POST /signApi/{sessionId}/seal

Triggers the signing of all documents added to the eStamp session. The call blocks until all documents are signed (maximum 60–120 seconds). Does not return a body.

Authentication: Bearer token required

Return: No body (empty 200 response)

# eStamp: Seal all documents in the session
# Endpoint: POST /signApi/{sessionId}/seal
# Return: no body (empty 200 response if successful)

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

Error messages:

[!WARNING] getDocument may only be called after a successful seal call. AgetDocument call before seal returns 404 Not Found.

GET /signApi/{sessionId}/getDocument/{documentId}

Retrieves a single signed document from the eStamp session. Must be called separately for each documentId (see figure 4).

Authentication: Bearer token required
Return: Signed PDF as binary (application/pdf); file name in response header

# eStamp: Retrieve signed document from session
# Endpoint: GET /signApi/{sessionId}/getDocument/{documentId}
# Return: signed PDF as binary

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

Error messages:

Successful Response (200 OK):

json

$body

Sig_OhneVisualisierung.pdf

Sig_MitVisualisierung.pdf
Figure 4: Depending on what is retrieved, the result is either a PDF document with or without a visual signature display. (You can view the result by clicking on the files.)

POST /signApi/{sessionId}/closeSession

Ends an eStamp batch signing session and releases all associated resources. Does not return a body.

Authentication: Bearer token required

Return: No body

# 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. However, manual closure using closeSession is still recommended in order to free up resources immediately.

Successful Response (200 OK)

Signature field endpoints

POST /signApi/signatureFieldNames

Returns the IDs of all existing signature fields in a PDF document. Used to determine signatureFieldId values for the signatureAppearanceconfiguration.

Authentication: Bearer token required
Content-Type: multipart/form-data
Return: JSON array of signature field IDs

# eStamp: Query signature field IDs of a PDF
# Endpoint: POST /signApi/signatureFieldNames
# Return: JSON array 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"

Example-Response (200 OK):

["Signatur1", "Signatur2", "Signatur3"]

The returned values can be used directly as signatureFieldId in the signatureAppearance-configuration. If signatureFieldId is set, x, y, width, height, firstPage, lastPage and onEveryPage are not required.

Validation endpoints

POST /signApi/validatePdf

Validates the signature of an existing PDF document and returns a validation report.

Authentication: Bearer token required
Content-Type: multipart/form-data
Return: Validation report as XML or PDF binary; file name in response header

# eStamp: Validate PDF signature
# Endpoint: POST /signApi/validatePdf
# 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

Request-Parameter:

Successful Response:
If the reportType is a pdf, then the return value looks like this: xmlReport.pdf

POST /xmlSignApi/validateXml

Validates the signature of an existing XML document and returns a validation report.

Authentication: Bearer token required
Content-Type: multipart/form-data
Return: Validation report as XML or PDF binary

# eStamp: Validate XML signature
# Endpoint: POST /xmlSignApi/validateXml
# 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

Request-Parameter:

Successful Response:

If the reportType is xml, then the return value looks like this: xmlReport.xml

signatureAppearance: complete field reference

The signatureAppearance configuration controls the visual appearance of the signature in the PDF. It is always transferred in JSON format — either as a file or as a server-side configuration (referenced via appearanceId).

Mandatory fields

Optional Fields

Supported signatureAttributes (X.509)

[!NOTE] The left value (e. g. subjectDn) is the technically fixed key. The right value (e. g. "Subject") is the freely selectable display text in the visualization.

[!WARNING] The following field combinations in signatureAppearance are not supported and will result in errors: signaturePageId together with onEveryPage: true (400 Bad Request), and visualizationAutomation together with signatureAttributes (unsupported combination).

visualizationAutomation: Mandatory fields

When visualizationAutomation is set, eStamp automatically positions the signature visualization at the end of the last text character on the last page. The following three fields are mandatory within thevisualizationAutomation block:

[!WARNING] When using visualizationAutomation, signaturePageId must be set to a valid value. signatureAttributes must not be set at the same time.

paraphenImage: Field reference

The initials configuration controls the display of a small signature image (initials) on defined pages of the document. It is passed as an optional JSON parameter to seal endpoints.

Mandatory fields

Example configuration:

{
  "paraphImageId": "picture1",
  "width": 50,
  "height": 22,
  "x": 10,
  "y": 800
}

Endpoint overview

All eStamp REST API endpoints at a glance: