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),checkbox_group(for a group of checkboxes to be checked by the participant),checkbox(for a checkbox to be checked by the participant).
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, Add a label field and Add checkbox fields.
Note that only signature and visa fields are set by default on your workspace. Before you can add other field types, ensure with us that their respective features are activated in your account.
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
Note that x and y coordinates values must not exceed the dimensions of the imported document, otherwise the API returns an error.
Use case
For an A4 portrait format document, the max dimensions are 595 (width) 841 (height). Knowing that a signature field’s default dimensions are 200 (width) and 50 (height) and that x and y coordinates define the position of the bottom left corner of the signature field, the maximum values of the field’s coordinates are:
x=395y=791
In this case, the signature field is placed in the top right corner of the document.
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
