A field is the object that bears the action to be performed by a participant. A field has a type which can be either:
signature(for a signature request by a physical person),visa(for a consultation request by a physical person),text(for a text field to be filled by the participant),label(for a read only text added by the transaction creator on a document).
You can also add initials fields.
This page presents only signature and visa fields. For more information about other field types, visit Add a text field and Add a label field.
Create a signature/visa field
To create a field, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields and pass the type argument, (either signature or visa) depending on whether you request a signature or a consultation of the document. You can optionally set a name for that field:
curl
https://api.universign.com/v1/transactions/tx_DwYGle91EQZA/documents/doc_4dn/fields \
-d type=signature
-d name=MyFieldName
Note that the default type is signature, so it is optional to pass it if you request a signature.
The API response returns a field sub-object.
{
"id": "fld_a998",
"type": "signature",
"built_in": false,
"consents": [],
"updatable": true,
"deletable": true
}
Create a signature field with a position on a document page
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. You can do so by passing the field’s coordinates on the document page or by using an anchor.
With coordinates
A field’s position can be defined by its page number as well as horizontal (x) and vertical (y) pixels coordinates. To create a field with a position in coordinates, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields and pass the position arguments (page,x and y):
curl
https://api.universign.com/v1/transactions/tx_DwYGle91EQZA/documents/doc_4dn/fields\
-d type=signature
-d name=MyFieldName
-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 create a field with with an anchor, 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_DwYGle91EQZA/documents/doc_4dn/fields\
-d type=signature
-d name=MyFieldName
-d page=1
-d anchor=client signature
It is not mandatory to pass the page number when using an anchor. However, it can be useful if the string you passed is found more than once across the document. If the string is found more than once within the same page, the system will position the anchor underneath the first occurrence only.
Notes:
visa fields are always invisible and cannot be positioned on a document page.
built-in fields are natively visible on the document and can neither be moved nor deleted.
Whether the field is visible on the document or not, all details about the signature, visa and seal operations are always displayed in Adobe’s signature panel.
The position of a field within the document can be set upon field creation or via an update. If you want to update the field position, pass the field ID in the request URL and set the position as indicated above. Here is an example update request:
curl
https://api.universign.com/v1/transactions/tx_DwYGle91EQZA/documents/doc_4dn/fields/fld_a998\
-d type=signature
-d name=MyNewFieldName
-d page=2 \
-d x=75 \
-d y=200
