Configuring dropdown field options from an external source

Please note that this feature is exclusively available with specific pricing plans.

Paperform's Dropdown fields allow you to use an external options list, ideal for situations requiring dynamic data. This is supported by configuring the field to import options from an external public API of your choice.

To set this up, you will need to take the following steps, described below.

1. Configure your external API source
2. Configure the Dropdown Field with your external list

Configuring your external API source

To use an external option list on Paperform, the output supplied by your API must provide data in the correct format.

Requirements

The response provided by your external API:

1. Must return the response in less than 1 second.
2. Is limited to 1000 options.
3. Should support filtering options with the query parameter: query

Data format

The values should match the following TypeScript definition:

type Option {
   string | {label: string, value: string|number}
}

type OptionsResponse {
 | Option[]
 | {
      options: Option[]
      hasMore: boolean
   }
}

The hasMore property

Use the hasMore property to notify Paperform that there are more options available. This will ensure that a search will be performed and sent to your API.

By explicitly setting the hasMore parameter to false, Paperform won’t request data from the endpoint for subsequent searches and will perform filters client side.

Allowing data to be queried

To ensure that users can filter the data in the dropdown, please implement the query query parameter on your API endpoint.

For example, https://mydomain.com/options?query=abc.

When returning a filtered list, please return the hasMore property in the response.

Examples

Here are some examples to help structure your own responses:

Example 1

[
   "Option 1",
   "Option 2",
   "Option 3",
]

Example 2

[
   {
      label: "Option 1",
      value: "option_1",
   },
   {
      label: "Option 1",
      value: "option_1",
   }
]

Example 3

[
   options: [
      {
         label: "Option 1",
         value: "option_1",
      },
      {
         label: "Option 1",
         value: "option_1",
      }
   ],
   hasMore: true,
]

Example 4

[
   options: [
      "Option 1",
      "Option 2",
      "Option 3",
   ],
   hasMore: true,
]

External Options Response JSON Schema

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "options": {
          "$ref": "#/$defs/options_array"
        },
        "hasMore": {
          "type": "boolean"
        }
      },
      "required": [
        "options"
      ]
    },
    {
      "$ref": "#/$defs/options_array"
    }
  ],
  "$defs": {
    "options_array": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "$ref": "#/$defs/options_object"
          },
          {
            "$ref": "#/$defs/options_string"
          }
        ]
      }
    },
    "options_object": {
      "type": "object",
      "properties": {
        "label": {
          "type": "string"
        },
        "value": {
          "type": [
            "string",
            "number",
            "integer"
          ]
        }
      },
      "required": [
        "label",
        "value"
      ]
    },
    "options_string": {
      "type": "string"
    }
  }
}

Configuring your Dropdown Field's external option lists

External option lists can be added directly when configuring a standard Dropdown field configuration.

Like the existing dropdown field, you can:

• Allow multiple options to be selected,
• Add an “other” option, and
• Select a default option from your initial list.

You can also manage external options lists on the Account Services page.

Considerations

• The data sent to the form will be truncated at 1000 options. If you would like to make more than this available, please supply the hasMore property in your response and make sure you support filtering via the query parameter on the request.

Gotchas

• Retrieving data from Google Sheets documents (for example via an Apps Script or Macro) is not currently supported.
• If you have forms that are using an external options list, you will need to remove it from your form before deleting it in Account Services.