📘

Goodbye server stamps, welcome electronic seals!

In the v3 of our API, we have renamed server stamps into electronic seal, to better fit with market standard for this product. Through this guide, we use the electronic seal name everywhere, even to refer to v2 server stamps.

📘

This guide is focused on migration

For a general overview of electronic seals, check the dedicated guide.

What has changed in v3?

Our V3 API for electronic seals has been revamped to offer a simpler experience of sealing documents. Here are the highlights.

Separate endpoints for images management

In V2, each call to create a seal required to pass the associated image as a base64 object. This was inefficient in terms of bandwidth and images library management. In the V3, there are now dedicated endpoints to manage seal images. You can then simply pass an image_id attribute upon creation of the seal to use that image in your seal. Note that this attribute remains optional, meaning you can still create seal without images (your documents will still be validly signed, as you can see when inspecting the signature).

Multipart upload of files

In V2, the document upload and image attribute required to use a base64-encoded version of the files. In V3, to provide a more efficient upload experience, we are using multipart file upload for these endpoints.

Extended fields management

In V2, fields were managed via the fileObjects array, which mixed concepts of seal fields and text fields (through mentions). In V3, we have introduced a clearer distinction between field types. The fields of type seal (which is akin to a signature) and the text fields can now be positioned independently of each other.

Addition of new fields

In v3, we are introducing several new fields that let you customize your seal:

• external_id: can be used to map a seal to your internal database (useful when retrieving seal webhooks and matching them with your own records)
• reason: a free text field that will be appended to the signature field and displayed when inspecting the signature with a PDF reader. It defaults to "Signed by Yousign"
• timestamp: a boolean field that lets you add a qualified timestamp to your seal. Note that this requires the activation of a dedicated add-on. Please contact your customer representative for further information on activation of this add-on.

Webhooks simplification

Similary to Webhooks for the signature requests, Webhooks are now defined at organization level and not at every seal creation. Note that events remain the same as in V2 (success and error). All details about migrating Webhooks from V2 to V3 can be found here.