Create an Electronic Seal

📘

Migrating from the v2 API

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

This guide will show you the minimum steps for creating a Simple or Advanced Electronic Seal. Refer to this guide if you don't know which level to choose.

Simple Electronic Seal

Step 1: Upload a Document

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}}",
  "total_pages": 2,
  "created_at": "2024-01-18T22:59:00+00:00"
}

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

Step 2: Seal the Document

You can now proceed with the actual Sealing of the Document. A typical Seal payload consists of 2 items:

• The document_id for the document to Seal (retrieved from the previous step);
• One or more fields, of which at least 1 field of type seal (see Add Fields to your Electronic Seal for more details on fields and how to use them).

For now, let us create a Simple Seal with 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 '
{
  "document_id": "{documentId}",
  "fields": [
    {
      "type": "seal",
      "page": 1,
      "height": 100,
      "width": 100,
      "x": 0,
      "y": 0
    }
  ]
}
'

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

Don't forget to replace documentId with the actual value retrieved from previous steps. A minimum of one seal type field is required in order to perform the Sealing.

After creation, your Seal will have a status of pending. This means that it is will soon be processed (see the different statuses here).

Step 3: Download your Sealed Document

Once the Seal has been processed (see the dedicated guide for that purpose), you can download the sealed document using Document download endpoint:

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

The signature panel in a PDF viewer will show you that the Document has been Sealed using Yousign's certificate.

Advanced Electronic Seal

Step 1: Upload a Document

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}}",
  "total_pages": 2,
  "created_at": "2024-01-18T22:59:00+00:00"
}

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

Step 2: Seal the Document

You can now proceed with the actual Sealing of the Document. A typical Seal payload for advanced Electronic Seal consists of 4 items:

• The document_id for the document to Seal (retrieved from the previous step);
• The certificate_id to use for the Sealing (this information was communicated to you when you registered to create the certificate);
• The signature_level set to advanced_electronic_signature to specify you want create an Advanced Electronic Seal;
• One or more fields, of which at least 1 field of type seal (see Add Fields to your Electronic Seal for more details on fields and how to use them).

For now, let us create a Simple Seal with 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 '
{
  "document_id": "{documentId}",
  "certificate_id": "{certificateId}",
  "signature_level": "advanced_electronic_signature",
  "fields": [
    {
      "type": "seal",
      "page": 1,
      "height": 100,
      "width": 100,
      "x": 0,
      "y": 0
    }
  ]
}
'

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

Don't forget to replace documentId and certificateId with the actual values retrieved from previous steps. A minimum of one seal type field is required in order to perform the Sealing.

After creation, your Seal will have a status of pending. This means that it is will soon be processed (see the different statuses here).

Step 3: Download your Sealed Document

Once the Seal has been processed (see the dedicated guide for that purpose), you can download the sealed document using Document download endpoint:

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

The signature panel in a PDF viewer will show you that the Document has been Sealed using your certificate.

Going further

Optional properties

• external_id: useful if you want to match a Seal with your internal system of records (for example when you are listening to webhooks for Seal completion);
• image_id: use an Image to represent the Seal with a custom visual printed in your document. See the dedicated guide to manage your Images.

Fields

See the dedicated guide to know more about Fields related to Electronic Seal.

Webhooks

See the dedicated guide to follow Electronic Seal status and related webhooks.