Dropdown fields (Enumeration)

Dropdown - a field with a number of preset options to fill in. Signer can either select one of the options available or type in a different option.

Dropdown fields can be editable (preset options + add your own option) or non-editable (preset options only).

This type of field in signNow is called enumeration.

Adding Dropdown fields to a document

To add a Dropdown field, document owners should open fields array in the request body, add a field and specify its "type" parameter as "enumeration".

Then, to add options, they should open another array called "enumeration_options" within the "fields" array. `

Dropdown field (Enumeration) example
"fields":[
{
            "page_number": 0,
            "type": "enumeration",
            "name": "EnumerationName",
            "role": "Signer 1",
            "prefilled_text": 123,
            "label": "EnumerationLabel",
            "required": true,
            "custom_defined_option": false,
            "enumeration_options": [
                "123",
                "43",
                "12345"
            ],
            "height": 40,
            "width": 50,
            "x": 100,
            "y": 32
}
]

Dropdown field parameters

Parameter Meaning
json_attributes.prefilled_text Here you enumerate dropdown options which Signer sees when opens a document
json_attributes.custom_defined_options false - allows Signer to select only from the enumeration options

true - allows Signer to select an enumeration option or add their own option
Custom_defined_options is a boolean

When you add custom_defined_options parameter to the dropdown field, remember, it requires a true/false response. To set the true/false options, use these values:

“1” - true
“” - false

Reading Dropdown fields in responses

  • In a response before sending a document to the recipient
    e.g. from GET /document/{{document_id}}
{
  "enumeration_options": [ // list of all the dropdown options
    {
      "id": "61ccd5a0359c4656acfa8f2af315397117c093a9",
      "enumeration_id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "data": "123", // value that Signers see as a dropdown option 
      "created": "1581345189",
      "updated": "1581345189",
      "json_attributes": "[]"
    },
    {
      "id": "32be55abedef4fbda41f44c24adc356408e5dde9",
      "enumeration_id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "data": "43",
      "created": "1581345189",
      "updated": "1581345189",
      "json_attributes": "[]"
    },
    {
      "id": "498c734dcc6d4ce7946edec3b5dc68303766918b",
      "enumeration_id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "data": "12345",
      "created": "1581345189",
      "updated": "1581345189",
      "json_attributes": "[]"
    }
  ],
  "fields": [
    {
      "id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "type": "enumeration",
      "role_id": "ed1fe6496119438081b464f15e47557837626908",
      "json_attributes": {
        "page_number": 0,
        "x": 100,
        "y": 32,
        "width": 50,
        "height": 40,
        "required": true,
        "name": "EnumerationName",
        "label": "EnumerationLabel",
        "prefilled_text": "123",
        "custom_defined_option": ""
      },
      "role": "Signer 1",
      "originator": "document.owner@signnow.com",
      "fulfiller": "signer1@gmail.com",
      "field_request_id": "4fc8b10b8eca4b628732e4875e8110189eb15c0a",
      "element_id": "4919a272771f4eafa006c1edb546dc6dc0fc45ab",
      "field_request_canceled": null,
      "template_field_id": null,
      "field_id": "4fc8b10b8eca4b628732e4875e8110189eb15c0a"
    }
  ]
}
  • In a response when the recipient selected the option in the Dropdown field

You can find the selected option in the texts array of the response. Its id parameter will be equal to the element_id parameter of the completed field in the fields array.

In the following example, Signer:

  • opened the document,
  • saw the Dropdown field with default value prefilled_text="123",
  • clicked on the Dropdown field,
  • selected the "12345" value,
  • saved the document.
{
  "enumeration_options": [ // list of all dropdown elements
    {
      "id": "61ccd5a0359c4656acfa8f2af315397117c093a9",
      "enumeration_id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "data": "123", // value of a dropdown option 
      "created": "1581345189",
      "updated": "1581345189",
      "json_attributes": "[]"
    },
    {
      "id": "32be55abedef4fbda41f44c24adc356408e5dde9",
      "enumeration_id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "data": "43",
      "created": "1581345189",
      "updated": "1581345189",
      "json_attributes": "[]"
    },
    {
      "id": "498c734dcc6d4ce7946edec3b5dc68303766918b",
      "enumeration_id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "data": "12345",
      "created": "1581345189",
      "updated": "1581345189",
      "json_attributes": "[]"
    }
  ],
  "fields": [
    {
      "id": "27ef4b0741574d4dbdd4aa39e734e3c55a526a22",
      "type": "enumeration",
      "role_id": "ed1fe6496119438081b464f15e47557837626908",
      "json_attributes": {
        "page_number": 0,
        "x": 100,
        "y": 32,
        "width": 50,
        "height": 40,
        "required": true,
        "name": "EnumerationName",
        "label": "EnumerationLabel",
        "prefilled_text": "123", // default value of the dropdown field
        "custom_defined_option": ""
      },
      "role": "Signer 1",
      "originator": "document.owner@signnow.com",
      "fulfiller": "signer1@gmail.com",
      "field_request_id": "4fc8b10b8eca4b628732e4875e8110189eb15c0a",
      "element_id": "4919a272771f4eafa006c1edb546dc6dc0fc45ab",
      "field_request_canceled": null,
      "template_field_id": null,
      "field_id": "4fc8b10b8eca4b628732e4875e8110189eb15c0a"
    }
  ],
  "texts": [
    {
      "id": "4919a272771f4eafa006c1edb546dc6dc0fc45ab",
      "user_id": "a954c1e8a45ff6bb0d233d8ac160bd4e3271ca94",
      "page_number": "0",
      "email": "signer1@gmail.com",
      "font": "Arial",
      "size": "10",
      "data": "12345", // the dropdown option selected by Signer
      "data_encrypted": null,
      "x": "298",
      "y": "278",
      "line_height": "12.00",
      "created": "1581419109"
    }
  ]
}

As a result of Signer’s actions, signNow created an element that contains Signer’s selection in the texts array. You can find it using field[].element_id in the texts array where texts[0].id == fields[0].id.

If the document owner didn’t make the Dropdown field required, and the Signer didn’t select any option in this field, the element in texts won’t be created. It means that the Dropdown field element hasn’t received any value from the Signer.

How to fill in Dropdown fields using API

To fill in the Dropdown field, make a PUT /document/{{document_id}} request. Enter the value as "data" parameter in the texts array.

curl -X PUT \
  https://api-eval.signnow.com/document/{{document_id}} \
  -H 'Authorization: Bearer {{access_token}}’\
  -H 'Content-Type: application/json' \
  -d '{
  "fields": [
{
    "x": 305,
    "y": 278,
    "width": 122,      
    "height": 20,
    "page_number": 0,
    "label": "select_dropdown",
    "role": "Signer",
    "required": true,
    "type": "enumeration",
    "prefilled_text":"123"
  },
{ 
  "texts": [
  {
      "page_number": 0,
      "field_id": "{{field_id_EnumerationName}}", // Selected value to put into the Dropdown
      "data":"12345", // Selected value to put into the Dropdown
      "client_timestamp": {{$timestamp}}, // UNIX timestamp, optional
      "x": 298,
      "y": 278,
      "font": "Arial",
      "line_height": 12,
      "size": 10
   }]
}