Contents 

• Overview
• Key Terms
• What are Global Lookup Lists?
• ⚠️ Important Notes
• Step-By-Step Instructions
  • Before You Begin: Prepare your CSV file
  • Access Global Look Up
  • Create a New List
  • Bulk Import Items via CSV
  • Preview a Lookup List
• Manage List Items
  • Edit a List Item
  • Archive a List Item
• Manage a List
  • Rename a List
  • Archive a List
• Next Steps

Overview

This step-by-step guide shows Organization Owners and Client Admins how to create and manage global lookup lists in Next. 
 

 ➡️ For information on adding lookup fields to forms, see Add a Lookup Field to a Form (coming soon).

Key Terms 

Here are a few terms you'll see throughout this article: 

What are Global Lookup Lists?

Global lookup lists are custom sets of options that applicants filling out a form can search through and select from. You build the list once at the organization level, and can use it across any form in any program, such as Profile Forms or Intake Forms. 

Use lookup lists when:

• Your list of options is too long to enter manually in a form field.
• The same set of options is needed across multiple programs.
• You want people to search for an option rather than scroll through a dropdown.

Who can create and use lookup lists: 

• Create and manage lists: Organization Owners and Client Admins
• Add lookup fields to forms: Organization Owners, Client Admins, and Program Admins

Example: 


 

⚠️ Important Notes

• A list's slug (unique ID) cannot be changed after it's created. Only the list name can be updated later.
• Item Values cannot be edited after they're saved. Only the Label ( the text applicants see) can be updated. This prevents data errors on forms that are already collecting responses.
• For client organizations managed by a partner: Lookup lists are private to your organization. Other organizations cannot see or use your lists, even if they're managed by the same partner. 

Step-By-Step Instructions 

Before You Begin: Prepare your CSV file

Your CSV file needs at least two columns: one for the Value and one for the Label. You can also include additional columns for extra information about each item, called metadata.

Example Data:

Example CSV: 

📌A few things to keep in mind:

• Each row in the CSV is one list item.
• Use headers “Value” and “Label” for the first two columns (not plural). 
• The Value must be unique for every row — no two items can have the same Value.
• Any additional columns are optional and will be imported as metadata — extra details stored with each item. Metadata can be used to show extra information beneath each option in search results, or to filter which options appear on a specific form. Your metadata column headers can be named anything.

Access Global Look Up  

1. Log in as an Organization Owner or Client Admin and click Settings in the top menu.
    
2. Select the Global Look up tab. 
   
   

Create a New List 

1. Click Create list in the upper-right corner. 
   
   
    
2. Enter a List Name (for example: “Departments”).

A slug will be automatically generated from the name you enter and displayed before you save. This is the unique code the system uses to connect the list to form fields. It cannot be changed after the list is created. 

3. Enter an optional Description for the list. 
    
4. Click Create & open. 
   
   

➜ If the list is created successfully, you'll be taken directly to the list's detail page where you can start adding items.
 

➜ If a list with the same slug already exists, you'll see the error “A list with this name already exists.” Enter a different name and try again.
 

Bulk Import Items via CSV

📌Note: Importing a CSV will not delete any existing items in your list. It only adds new items or updates existing items (when applicable). 

1. On the Lists page, click the name of the list to open it. 
   
   
2. Click Upload CSV in the upper-right corner. 
   
   
3. Select your CSV file and upload it. 
    
4. You'll see a column mapping screen: 
   
   
    
   • The number of rows detected from your CSV will be shown in the top right.
   • The CSV column shows the headers of the columns in your CSV file.
      
5. Use the Role dropdown to assign a role to each column: 
   
   
   
   Each column in your CSV needs to be assigned a role so the system knows what to do with it. Value and Label are required — everything else is optional.
    
   • Skip: Ignores the column and excludes it from the import.
      
   • ⚠️Value (unique id) - required: The unique code the system uses to identify each item. Each value must be unique (for example, missoula-county-ps).
      
   • ⚠️Label (display) - required: The text people will see when filling out the form. For example, "Missoula County Public Schools."
      
   • Metadata: Extra information stored with each item. Metadata can be displayed beneath each option in search results and used to filter which options appear on a form.
     
     ➜ For any column assigned the Metadata role, complete the Stored as field (This is what the metadata column will be called in the system). 
      
     • If this is your first import: Enter a name for the new metadata column.
       
       
        
     • If your list already has metadata columns: You'll see a dropdown. Select New column: [name] to create a new column, or Map to: [existing column] to map it to one that already exists. Check this carefully to avoid creating duplicate metadata columns.
       
       
       
        
6. Click Preview import to review a summary of what will happen when the import runs. 
   
   
    
7. Review the summary carefully. If you see any errors, click Back to return to the mapping screen, fix the flagged rows in your CSV, and re-upload.
   
   
   
   The preview screen shows a breakdown of what will happen when the import runs. Here's what each item means:

a. To create: New items that don't yet exist in your list and will be added

b. To update: Existing items whose Label or metadata is being changed (Note: The value cannot be changed).

c. Unchanged: Existing items with no changes

d. Duplicate rows: Rows that appear more than once in your CSV. If duplicates exist, the last row will be used.

e. New metadata cols: New metadata columns being added to your list, listed by name in the orange banner at the bottom of the screen.

➜ If new metadata columns are being added, you'll see an orange banner at the bottom of the screen listing them by name. Review this carefully to make sure the column names are correct before continuing. 
 

f. Missing from CSV: Rows where a required field (Value or Label) is empty. These will also appear in the Errors table with the row number and reason.

e. Errors: Rows that can't be imported. An Errors table will appear at the bottom of the screen that explains the reason. 

Example Error: 


 

8. When everything looks right, click Run import.
   
   
    
9. A confirmation message appears summarizing the import. If there are errors, they will be noted in this message.
   
   
    
10. The imported items will appear in the list. 

Preview a Lookup List

Once you've added items to your list, you can test how it will behave on a form before attaching it to one.

1. From the list's detail page, click the Try it tab.
   
   
    
2. Type in the Live preview search box on the left to see how your list items appear to people filling out the form.
   
   
    

3. Use the Field settings on the right to try different options in the Preview. If your list stores metadata (extra details) for each item — like a school's county or state — you can use the metadata settings to show or filter by those details..
   
   ⚠️IMPORTANT: Changes you make here only apply to the preview, not actual form fields. To learn how to configure these settings on an actual form field, see ➡️ Add a Lookup Field to a Form (coming soon).
    

   
    

Manage List Items

Edit a List Item 

1. From the list’s detail page, find the item you want to edit and Click Edit. 
   
   
    
2. Update the Label or any metadata fields. 
   ⚠️IMPORTANT: You cannot edit an item’s Value.
   
   
    
3. Click Save. A confirmation message will appear in the bottom left. 
   
   
    

Archive a List Item 

📌Note: Archiving a list item removes it as an option for future applicants but does not affect any applications that have already been submitted. 

1. To archive an item, find the item you want to archive in the list and click the Archived toggle. You'll see a confirmation: "Item archived." The item will no longer appear as an option on forms.
   
   

➜ To unarchive a list item, click the toggle again. You'll see "Item unarchived" and the item will become available on forms again.

 

Manage a List

Rename a List

1. On the Lists page, click Rename on the far-right of the list.
   
   
2. In the pop-up, enter the new Name and optional Description, then click Save. A confirmation message will appear in the bottom left. 
   
   ⚠️IMPORTANT: Renaming a list does not affect its slug or any forms already using the list.
   
   

Archive a List

📌Note: Archiving a list removes it from your form builder and any forms currently using it will stop displaying options. Submitted applications are not impacted.

1. On the Lists page, click Archive on the far-right of the list.
   
   
    
2. A confirmation message appears in the bottom-left. The list item is grayed out and shows the tag “Archived.” 
   
   
   
   ➜ To unarchive the list, click Unarchive on the far-right. A confirmation message appears, and the list is available again.
    

Next Steps

Once your list is ready, you can add it to a form. See ➡️ Add a Lookup Field to a Form (coming soon).

What did you think of this article? Please leave a comment below! 
Your feedback helps us improve the experience for everyone.