What is an electronic seal, and how does it compare with signatures?

An electronic seal guarantees the integrity of a document. It is a specific form of electronic signature, where:

• The signer is an organisation, not an individual
• There is always only one signer (the organisation)

An electronic seal is like a digital version of ink stamps used by companies to seal documents.

Like Signature Requests, the signature certificate gets embedded in the document after sealing. This certificate is what gives a seal its legal value. To visualize the seal, a sealed document can also contain a seal image which can be customised at the time of sealing. This image has no legal value in itself, but reinforces the perception of the seal (like the visual scripts for signatures).

Seals are used in very specific business processes. Because of this, the operations that you can realise with the electronic seal API are simpler than the signature API. The main operations you can realise with the API are

• Managing images used to visualise the seal
• Uploading a document and sealing it
• Retrieving a sealed document

Other operations and resources are not relevant because of the nature of the seal (e.g. there is no signers management).

How to create your first seal?

📘

Migrating from the v2 of the API

If you were using the v2 of the API, read this note first to understand how the API evolved: Migrating from server stamps to electronic seals.

🚧

Sandbox availability

To try out the sealing API in Sandbox, please reach out to our teams so that they can activate this feature on your account.

Upload a seal image

When you seal a document, you can optionally represent the seal with a custom visual printed in your document. To avoid uploading that image for each seal, you can manage images from a specific endpoint. Images should be of format JPEG, PNG or GIF and should not exceed 500ko. Make sure that the image is small enough to fit on your documents.

Once you have selected your image, upload it with the images upload endpoint:

curl --request POST \
     --url https://{baseUrl}/electronic_seal_images \
     --header 'Authorization: Bearer {apiKey}' \
     --header 'accept: application/json' \
     --header 'content-type: multipart/form-data'
     --form 'file=@"/Users/user/image.png"' \
     --form 'name="My seal image"'

{
  "id": "{{imageId}}",
  "name": "My seal image",
  "created_at": "2024-01-18T22:59:00+00:00"
}

Note its id, so you will be able to use it when sealing your document.

You can store up to 50 electronic seal images per organisation. The API exposes endpoints to manage your images: list, download and delete. Deleting an image will not invalidate the seals previously created with it.

Upload a document

Now that you have configured a seal image, upload the document to seal. The document must be a PDF. All constraints that apply to signature documents also apply to electronic seal documents. Note that your document can also be password-protected, like signature documents.

Upload your document with the electronic seal documents upload endpoint:

curl --request POST \
     --url https://{baseUrl}/electronic_seal_documents \
     --header 'Authorization: Bearer {apiKey}' \
     --header 'accept: application/json' \
     --header 'content-type: multipart/form-data' \
     --form 'file=@"/Users/user/document.pdf"'

{
  "id": "{{documentId}}",
  "created_at": "2024-01-18T22:59:00+00:00"
}

Note its id, so you will be able to reuse it for the actual sealing.

Seal the document and retrieve it

You can now proceed with the actual sealing of the document. A typical seal payload consists of 4 items:

• The id of the document to seal (retrieved from the previous step)
• The optional signature_level of the seal: can be either electronic_signature (simple seal) or advanced_electronic_signature(advanced seal). This field defaults to electronic_signature if you do not provide a value in your payload. See how to choose the right seal level .
• The optional id of the image to use to represent the seal (retrieved from the first step)
• An optional external_id to attach to the seal. This is useful if you want to match it with your internal system of records (for example when you are listening to webhooks for seal completion)
• One or more fields, of which at least 1 field of type seal (see next section for more details on fields and how to use them)

For now, let us create a simple seal with only one image on the first page of the document. We do so using the electronic seal creation endpoint:

curl --request POST \
     --url https://{baseUrl}/electronic_seals \
     --header 'Authorization: Bearer {apiKey}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "image_id": "{imageId}",
  "document_id": "{documentId}",
  "external_id": "my-external-id",
  "fields": [
    {
      "type": "seal",
      "page": 1,
      "height": 250,
      "width": 250,
      "x": 0,
      "y": 0
    }
  ],
  "timestamp": false
}
'

{
  "id": "1365283d-0ba5-4a08-9a58-9818ef428320",
  "status": "pending",
  "created_at": "2024-01-18T22:59:00+00:00",
  "document_id": "{{documentId}",
  "timestamp": false,
  "image_id": "{{imageId}}",
  "external_id": "my-external-id"
}

Don't forget to replace imageId and documentId with the actual values retrieved from previous steps.

After creation, your seal will have a status of pending. This means that it is will soon be processed (see the different statuses here). In a production-grade implementation, use webhooks instead to track status changes. After a few instants, you can download the sealed document using the electronic seal documents download endpoint:

curl --request GET \
     --url https://{baseUrl}/electronic_seal_documents/{documentId}/download \
     --header 'Authorization: Bearer {apiKey}' \
     --header 'accept: application/pdf' \
     --output 'document.pdf'

When opening the document, you will see that it contains the printed seal visual. The signature panel in a PDF viewer will also show you that it has been sealed using Yousign's certificate.

How to work with electronic seal fields?

Upon sealing, you can add fields in the document to seal. You can add up to 200 fields to a document, and there must always be one field of type seal (see more on this type below).

📘

Placing fields in your document

When you place fields in your document, you will need to provide their page, width, height and coordinates (just like for signature fields). To help you with this, you can use our fields placing tool.
Note that smart anchors cannot be used for electronic seal fields.

Fields of type seal

Image

Fields of type seal are used to place visual representation of the seal in the document. Configure the image using the top-level image_id attribute in the seal payload. If you do not want any image, omit the image_id field, and pass values of 1 for all page, height, width, x and y attributes.

You can print the same image in many locations of your document, but you cannot use different images in the same document.

Reason

Each field of type seal can also have a optional reason. This reason is a string of text displayed with the signature certificate (it holds no legal value in itself). It defaults to "Signed by Yousign" if you don't provide any value.

Fields of type read_only_text

Text

Fields of type read_only_text are used to print text on your document at the time of sealing. This text, provided with the text attribute, can typically be used for adding mentions next to the visual of the seal (e.g., date of the seal, internal reference...). You can add many text fields (e.g. one above and one below each seal). You can also use such fields without a visual seal image.

How to select the right level for your seal?

Like for Signature Requests, the eIDAS regulation defines several levels of electronic seals. We currently support simple and advanced levels. The below table lists typical use cases for these levels. Please reach out to your customer representative to advise on the level best suited for your use case.

Finally, please note that the advanced seal requires the creation of a certificate dedicated to your organization. This is a process that involves identity verification for a legal representative from your company. Please reach out to your customer representative to enquire about the actions required to activate this level.

What are electronic seal statuses?

Electronic seals have only a limited number of statuses, summarised below.