Pulling data from an external CSV

Last updated: 25 Nov 2025

The pulldata() function in XLSForm lets you dynamically retrieve information from an external CSV file while completing a form. This allows you to reference existing datasets and automatically pull in related details, avoiding the need for enumerators to re-enter the same information.

For example, you can use pulldata() to:

  • Auto-fill related information: When an ID, code, or key is entered, automatically retrieve linked details such as a name, category, or description.

  • Preload background data: Load information from external files so enumerators only need to collect new or updated data.

Using pulldata() helps reduce errors, saves time during data collection, and ensures that forms remain consistent with external reference datasets. This function is supported in both the KoboCollect Android app and Enketo web forms. We recommend using XLSForm to set up the pulldata() function.

This article covers the following steps for pulling data from an external CSV:

  • Setting up your external CSV

  • Setting up your XLSForm

  • Uploading your external CSV to KoboToolbox

Setting up your external CSV

To use pulldata(), first prepare an external CSV file containing the reference data you want to retrieve. Each row should represent a unique record (for example, a participant, location, or item) and the file should include at least two columns. One column must contain the index variable that matches the values entered in your form.

The index variable acts as the primary key that links your XLSForm to the external CSV. It should be a unique identifier that exists in both files, such as a participant ID, a district name, or another matching code.

The remaining columns can include any additional details you want to retrieve, such as names, categories, or descriptions. Ensure the CSV file is clean, consistently formatted, and saved with the .csv extension.

Setting up your XLSForm

Once you have set up your external CSV, configure your XLSForm in the following way:

  1. Ensure your XLSForm includes a question that serves as the index variable.

  2. Add a calculate field to your survey. Give the field a name.

  3. In the calculation column, use the pulldata() function to specify which field in the CSV to pull from. Use the following syntax: pulldata('csv','pull_from', 'csv_index', '${survey_index}').

    • csv is the name of the CSV file, without the extension.

    • pull_from refers to the column in your CSV file that contains the data you want to import into your form.

    • csv_index is the column in your CSV file that contains the index variable.

    • survey_index is the name of the question in your survey that contains the index variable.

survey worksheet

type

name

label

calculation

text

respondent_id

Respondent ID

calculate

eligibility_status

pulldata(‘eligibility’, ‘status’, ‘ID’, ‘respondent_id’)

note

eligibility_not

Respondent is ${eligibility_status} for the study.

survey

In the example above, the calculation retrieves the value from the status column of the eligibility.csv file, in the row where the ID in the CSV matches the ID entered in the respondent_id question of your form.

Note: After using the pulldata() function to retrieve external CSV data, you can reference that field in subsequent skip logic conditions, constraints, and labels, just like any other field or calculation.

Uploading your external CSV to KoboToolbox

The final step in linking your external CSV file to your form is uploading the file to KoboToolbox. To do this:

  1. Navigate to your project SETTINGS, and open the Media tab.

  2. Upload the CSV file(s) with the exact name you have used in your XLSForm.

  3. Deploy or redeploy the form.

Upload media

Troubleshooting

Non-English fonts or special characters are not displaying correctly Save your CSV file in UTF-8 format. This ensures that Android devices can render non-English text or special characters properly.

Numeric values are not working as expected All data pulled from a CSV file is treated as text. To use these values as numbers, apply the int() or number() functions to the retrieved value in your XLSForm.

Protecting sensitive data If your CSV contains sensitive information that you do not want uploaded to the server, upload a blank CSV file with your form. Then manually replace it on each device with the real CSV file. This approach only works with the KoboCollect app.

Slow form loading with large files If you are using very large CSV files, you may experience slow form loading in KoboCollect. To resolve this, we recommend using the trigger column to pull data from the external file once, rather than recurrently in the background.

Pulling dates from external CSV files If you are storing dates in an external CSV file and want to pull them into a form, ensure they are in the format YYYY-MM-DD. If you are editing your CSV in Excel, add a single quote ' in front of the date to avoid automatic date formatting in Excel.

Pull data not working properly If the pulldata() functionality is not working properly, try the following:
  • Rename your CSV file to remove underscores or special symbols.
  • Check that your CSV file is adequately set up with one variable per column (see Community Forum post).
  • Check that you are using the exact spelling for file names and column names.
  • Check that the cells in your CSV file do not include extra spaces before or after the value.