Add a signature/visa field

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),
• radio_group (for a group of radio buttons to be checked by the participant),
• radiobutton (for a radio button to be checked by the participant),
• dropdown (for a dropdown list where the participant needs to select an option).

You can also add initials fields.

This page presents only signature and visa fields. For more details about other field types, visit Add a text field, Add a label field, Add checkbox fields, Add radio button fields and Add dropdown list 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.

• 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.

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=395
• y=791

In this case, the signature field is placed in the top right corner of the document.

To make sure your signature field is well positioned in the transaction document, below is a reminder of the max dimensions of the most common document formats:

• A4 portrait document: width=595 / height=841
• A4 landscape document: width=841 / height=595
• A3 portrait document: width=841 / height=1190
• A3 landscape document: width=1190 / height=841

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.

If you do not set any x and y coordinates, the signature cartridge is automatically positioned on the first character of the anchor.

Note that in this case, x and y coordinates define the position of the signature cartridge relative to the anchor.

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    

---

Revoke documents download

← Previous

Add a text field

Next →