Prerequisites
A seal is a signature by a legal person. To activate the seal feature, your workspace must own a certificate for legal person, issued by Universign upon demand.
To request a document to be sealed by a legal person, you must first create a signature field and then, assign a seal ID to that field.
Create a signature field
To create a field, send a request to POST /v1/transactions/{transaction_id}/documents/document{id}/fields and pass signature in the type argument (note that this is the default value, so it is not mandatory to set the type.)
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields \
-d type=signature
You are returned a field ID in the API response:
{
"id": "fld_a998",
"type": "signature",
"built_in": false,
"consents": [],
"updatable": true,
"deletable": true
}
Note that the size of the seal is set to 200px x 50px and cannot be edited. Make sure the seal is well positioned in the document. If any edge of the seal exceeds the document limit, the API returns an error.
Assign a seal ID to the field
To request the document to be sealed, send a request to POST /v1/transactions/{transaction_id}/signatures and pass the field ID (via the field argument) and the seal ID (via the signer argument), as follows:
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/signatures \
-d signer=scd_5x \
-d field=fld_a998
Authorize a qualified seal to be used
You may need to affix a qualified seal on a document using a QCP-l-qscd certificate for legal person (LPC). This endpoint, allows you to authorize the use of a QCP-l-qscd certificate for legal person to be used within a transaction. As it is a higher level certificate, the use of the seal needs to be authorized by setting the PIN code previsouly initialized for the certificate.
To do so, send a request POST /v1/transactions/{transaction_id}/sealers/{seal_id}/authorize and pass the PIN code of the certificate in the auth_data[ ].value argument, as in the request example below. The ID of the authentication means must be appended to the auth_data[ ].value argument between brackets (for example auth_data[atm_Bw3e].value).
Note that you can retrieve the authentication means ID from the Certificates section of your workspace.
curl https://api.universign.com/v1/transactions/tx_qoMGgYXm7AX3/sealers/lpc_Ao3dEYn0eonZ/authorize \
-d auth_data[AuthenticationMeansID].value="12345678"
Note that for any certificate creation requests, you need to contact your account manager at Universign.
The API returns a seal sub-object.
Response example
{
"id": "lpc_Ao3dEYn0eonZ",
"name": "QCPlqscd certificate",
"label": "QCPlqscd certificate",
"logo_display": "issuing_entity"
}
Update a seal logo
You may need to use a custom logo for the seal that will display on your document. You can use either the Universign logo, the issuing entity logo or even seal a document with no logo. This endpoint, allows you to define the logo that will display on your sealed document.
To update the logo that will display on your sealed document, send a request to POST /v1/transactions/{transaction_id}/seals/{seal_id} and pass the logo_display argument:
curl https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/seals/scd_5x \
-d logo_display=issuing_entity
The logo_display accpeted values are as follows:
certifcate: if you want to use the Universign logoissuing_entity: if you want to use the issuig_entity logo (default value)none: if you don’t want to use any logo
The API returns a seal sub-object.
{
"id": "scd_5x",
"name": "scdName",
"logo_display": "issuing_entity"
}
Customize a seal logo (Full transaction request only)
You may need to use a custom seal logo while requesting a full transaction. To do so, you need first to own a certificate for legal person. Then, add the certificate id and the signature_image arguments to your full transaction request. Note that you can set signature_image only if logo_display value is certificate.
"sealers": [
{
"id": "scd_wa7ZVZGxzOq0",
"signature_image" : "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"
}
]
Requirements
- The seal logo is passed in base64.
- The seal logo must not exceed 2 MB.
- Only PNG and JPG formats are accepted.
For more details about the full transaction request, visit Full transaction request.
Remove a signer from a field
You can remove a signer from a field. To do so, add the delete argument to your request and set it to true.
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/signatures \
-d signer=scd_5x \
-d field=fld_a998 \
-d delete=true
Position a field
A seal can be visible or invisible in the PDF. When you create a field, it is by default invisible but you can specify its position on a document page.
You can specify the field position by setting its coordinates on the document page or by using an anchor:
With coordinates
A field’s position is defined by the page number as well as horizontal (x) and vertical (y) pixels coordinates. To specify the position, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields/{field_id} and pass the position arguments:
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields/fld_a998 \
-d page=1 \
-d x=75 \
-d y=200
With an anchor
Universign can search for a string in the document and automatically position the signature field underneath it. To position the field, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields and pass the string value as the anchor argument:
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields \
-d anchor=client signature
Note that the position of a field can be set upon field creation via the endpoint (POST /v1/transactions/{transaction_id}/documents/document{id}/fields), or when the field already exists via the endpoint (POST /v1/transactions/{transaction_id}/documents/{document_id}/fields/{field_id}).
Multiple fields
You can create as many signature fields as needed in the document.
For more options on fields, visit add a field.
