Add dropdown list fields

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 example options[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 is 19.
  • width: The width of the field (expressed in PDF’s default user space units). Default value is 200.
  • required: Whether the participant must choose an option or not. Set only if field type is dropdown. Default value is true.

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] and options[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:

  1. Unassign the participant assigned to the dropdown list.
  2. 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.


Add radio button fields
Duplicate a field
Developer tools
Guides
Services
API reference