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 dropdown
list fields. For more details about other field types, visit Add a signature/visa field, Add a text field, Add a label field, Add checkbox fields and Add radio button 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.
Add a dropdown list field
The dropdown list field allows the participant to select one value from a list of options.
To create a dropdown list, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields
and pass dropdown
in the type
argument, the dropdown list unique name in the name
argument and page
, x
and y
arguments.
Note that if you want to delete a dropdown list option, you simply need to remove it’s associated options[key]
argument during the field update.
curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields \
-d type=dropdown \
-d name=DropdownList1 \
-d page=1 \
-d x=220 \
-d y=154 \
-d options[key1]=Option1 \
-d options[key2]=Option2 \
-d value=Option2 \
You can pass optional arguments:
options[key]
: To add a dropdown option, you must specify it as a key-value pair. The value of the options key must be appended to the options field between brackets (for exampleoptions[key]
), and must not exceed 20 characters. The option key-value pair must be unique within the same dropdown list and the value must not exceed 200 characters. You can add up to 15 options per dropdown list field. Note that the options value cannot be left empty and must not contain a backslash\
.value
: the value of the dropdown option that will be selected by default for the dropdown list. If set, the value cannot be left empty and must not exceed 200 characters. The option value must not contain a backslash\
.height
: The height of the field (expressed in PDF’s default user space units). Default value is19
.width
: The width of the field (expressed in PDF’s default user space units). Default value is200
.required
: Whether the participant must choose an option or not. Set only if field type isdropdown
. Default value istrue
.
The API response returns a field
sub-object.
{
"id" : "fld_MnLA",
"name" : "DropdownList1",
"type" : "dropdown",
"position" : {
"page" : 1,
"x" : 220,
"y" : 154,
"width" : 200,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"max_length" : 27,
"font_size" : 12,
"options" : {
"key1" : "Option1",
"key2" : "Option2"
},
"value" : "Option2",
"required" : true
}
Update a dropdown list field
You can update a dropdown list field. To do so, send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields/{field_id}
.
curl
https://api.universign.com/v1/transactions/tx_DwYGle91EQZA/documents/doc_4dn/fields/fld_MnLA \
-d name=Updated DropdownList \
-d page=1 \
-d x=220 \
-d y=154 \
-d options[key2]=Option2 \
-d options[key3]=Option3 \
-d options[key4]=Option4 \
-d value=Option4 \
In the request example above, the dropdown list field has been updated as follows :
options[key1]
was removed,options[key3]
andoptions[key4]
were added,value
has been updated.
This means that whenever you send a request to update a dropdown list field, you need to pass the options[*]
arguments of the options you want to keep or update, otherwise, the missing options[*]
you don’t pass will be automatically deleted (options[key1]
in this case).
The API response returns a field
sub-object as it was last updated.
{
"id" : "fld_MnLA",
"name" : "Updated DropdownList",
"type" : "dropdown",
"position" : {
"page" : 1,
"x" : 220,
"y" : 154,
"width" : 200,
"height" : 19
},
"built_in" : false,
"updatable" : true,
"deletable" : true,
"max_length" : 27,
"font_size" : 12,
"options" : {
"key2" : "Option2",
"key3" : "Option3",
"key4" : "Option4"
},
"value" : "Option4",
"required" : true
}
Move a dropdown list field
You can move a dropdown list field to another page of the same document or to another document. Send a request to POST /v1/transactions/{transaction_id}/documents/{document_id}/fields
and pass the target document in the URL and the field ID you want to move in the move_from
argument:
Curl
https://api.universign.com/v1/transactions/tx_DwYGle91EQZA/documents/doc_aJ4k/fields \
-d move_from=fld_MnLA
For more details, visit Move a field.
Delete a dropdown list field
In order to delete a dropdown list, you need to:
- Unassign the participant assigned to the dropdown list.
- Delete the dropdown list field.
Note that you cannot delete a dropdown list if the assigned participant has already performed his/her action (review or signature).
To delete a dropdown list, send a request to DELETE /v1/transactions/{transaction_id}/documents/{document_id}/fields/{field_id}
.
curl
https://api.universign.com/v1/transactions/tx_qE67Zr640eVX/documents/doc_bd2a/fields/fld_6WL \
-X DELETE
Note that built-in dropdown list fields cannot be deleted.