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 typeseal
(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 toadvanced_electronic_signature
to specify you want create an Advanced Electronic Seal; - One or more
fields
, of which at least 1 field of typeseal
(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.
Seal & Sign
You can use your sealed document into a signature request and perform a seal and sign process in few steps.
Add the downloaded sealed document to your Signature Request or use directly its id
, as described in Seal and Sign the same document .
Updated 2 months ago