To request the signature of a document by a physical person, you must first create a signature field on the document and then, assign a signer to that field.
Create a signature field on the document
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 signature is the default value, so it is not mandatory to set the type in that case.)
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
}
Assign a signer to the field
To assign a signer to a field, send a request to POST /v1/transactions/{transaction_id}/signatures and pass the field ID and the participant email in the request arguments:
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/signatures \
-d signer=john@company.com \
-d field=fld_a998
If the document can be signed indifferently by more than one person, you may want to set alternate signers. All you have to do is to assign several signers to the signature field. The first person who signs will close the signature task and if other participants try to sign the document, they will be indicated that the task has been completed and no more action is required from them.
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/signatures \
-d signer=john@company.com \
-d signer=alice@company.com \
-d signer=carol@company.com \
-d field=fld_a998
Remove a signer from a field
You can remove a signer from a field. To do so, add the delete boolean to your request and set it to true.
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/signatures \
-d signer=john@company.com \
-d field=fld_a998 \
-d delete=true
Position the field
A signature field can be visible or invisible in the PDF. When you create a signature field, it is by default invisible but you can specify its position on a document page. Note that even if the field is invisible in the document, the technical details related to the electronic signature are always visible in Adobe’s signature panel.
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.
