Populating an option list from an external source (e.g. CSV file) is very useful for long option lists (e.g. countries) or dynamic option lists that often changes. This article explains how to populate select options for select (one/many) fields and cascade fields.


Note: The size of the CSV file referenced in a form will impact the performance and usability of the form. Particularly launching or resuming a form, adding repeats and completing choice fields (selects and cascades) with external sources. This is compounded by the number of fields in the form that use CSV files. 

For devices with specs on the lower end, we would recommend a maximum of 1 000 rows. For devices with specs on the higher end, we would recommend a limit of 10 000 rows in the CSV file.


If the form contains multiple cascade fields with external sources (CSV files), we would recommend reducing the number of rows in the CSV file for better performance.


Select one/many fields


Open the Option list tab of your select field and navigate to "Get options from a source file".



  1. Once you have uploaded the CSV file containing your options into your workspace's resource library, select it from the 'Source file' drop-down.
  2. Choose the source column for the option label (text).
  3. Choose the source column for the option value.
  4. You can download a template CSV file to populate and upload to your workspace resource library.



By default, options will be listed vertically. For long option lists you can select "Searchable option list" from the Advanced settings tab. Configuring the display of option lists is covered in our article on appearance settings.


If you are subscribed to the standard plan or above, it's possible to filter the option list available to a data collector based on static values, other fields in the form, or columns in the CSV file. Detailed steps and examples for filtering option lists are covered here.



Cascade fields


Similar to select one/many fields, options can be populated from an external source like a CSV for example.


Open the Option list tab of the cascade field and select "Get options from a source file". 



  1. Once you have uploaded the CSV file containing your options into your workspace's resource library, select it from the 'Source file' drop-down. The format of the CSV file is important and it must contain columns that relate to each level in your cascade - e.g. if your cascade will have three levels: Country > District > City your CSV file should contain a column for each level.
  2. Enter a heading for each level of the cascade.
  3. Choose the source column to use for the option text (label) for each level.
  4. Choose the source column to use for the option value for each level.
  5. You can download a template CSV file to populate and upload to your workspace resource library.




Note on multilingual forms: 

If your form has been translated into multiple languages, you can add columns in your CSV file for each translation. Simply specify the column to use for the text. This will need to be specified for each language that the form has been translated in. Values are used as field identifiers for data analysis and will remain the same across all languages.



CSV file resource


Additional validation rules are applied to both the header and data rows of a CSV file resource to ensure issues do not occur during data collection. 

  • Header values can only contain letters, numbers or underscores and must begin with a letter. No spaces or other special characters are allowed in headers. The length of a header value cannot exceed 100 characters.
  • Data values can contain any characters except for double quotes " or backticks `.
  • It is best practice to remove spaces from the value columns (replacing spaces with underscores is a good alternative).
  • CSVs cannot be uploaded on free community plans. This is only available to paid plans.


Note: Steps to upload resources (e.g CSV files) to your resource library is covered in detail here.