The changes between REST API old Optimizer and New Optimizer may require some smaller adjustaments of the client implementations, but are in general not requiring big-effort changes. This migration guide should give an overview on how to migrate from old Optimizer to New Optimizer.

Conceptual Changes

The new Optimizer is redefining the routing structure by transitioning from the previous format of all routes strictly using /api/v1 in the path component to a new format that utilizes /signbox/api/v1.

Changes in API Calls

Modified calls

POST /signbox/api/v1/sign

Previous endpoint: POST /api/sign
Current endpoint: POST /signbox/api/v1/sign

Introduced Parameters

The following parameters have been added to extend functionality and control:

• certificate_check
  Validates the status of the signing certificate.

• sessionid
  Identifier of the session previously opened with POST /signbox/api/v1/open_session.
  Required for certain digital identities.

• useasync
  Enables the asynchronous signing flow.
  Asynchronous mode is active by default.

Timestamp Configuration

Previously, timestamp parameters were configured through an alias.ini file. These settings can now be included directly in the API request:

• tsa_url – URL of the timestamp service (required for T or LTV-level signatures)

• tsa_user – Billing username for the timestamp service

• tsa_pass – Billing password for the timestamp service

Signature Appearance (New Parameter)

In earlier versions, image-related settings were provided as separate fields. These have now been centralized into a new parameter: signature_appearance.

This parameter allows you to define all visual aspects of the signature in JSON format.

Example of signature_appearance:

All previous image configuration parameters should now be included within signature_appearance.

For a full list of available fields and options, please consult the API reference documentation

Added calls

The newly introduced calls therefore are:

OTP Management

• POST /signbox/api/v1/open_session

• POST /signbox/api/v1/close_session

Image Management

• POST /signbox/api/v1/image

• GET /signbox/api/v1/image/{image_uid}

• DELETE /signbox/api/v1/image/{image_uid}

• GET /signbox/api/v1/images

• DELETE /signbox/api/v1/images

Token Management

• POST /signbox/api/v1/token

• GET /signbox/api/v1/token/{token_uid}

• DELETE /signbox/api/v1/token/{token_uid}

• GET /signbox/api/v1/tokens

Timestamp

• POST /signbox/api/v1/timestamp

Changes in the response structure

Sign

The sign call now returns the following structure. Previously, it only included the ID of the process.

The new structure provides:

• The signature status

• A message confirming the creation of the process

• A detail object including the status, signature format, environment, and job ID

Example response from sign call:

Webhook (url_back) Notification

The webhook configured via url_back will receive a callback with the same structure as the main response, but with an updated message and status depending on the outcome of the signature process.

Example – Success Callback

Example – Error Callback

In case of an error during the signing process, the webhook will also receive the same structure with status: "error" and a descriptive message:

This uniform structure allows for easier integration and consistent handling of all signature status updates—whether successful or failed.