Simple 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.

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.