SmartumPlus
      Back to home
      1. Help Center
      2. Employers
      3. SmartumPlus

      Adding and updating benefit users with a CSV file

      A CSV file allows you to quickly and efficiently add or update a large number of employees at once. Follow the instructions below for a smooth data transfer process.

      Download CSV template

      Add or update data in the CSV file

      Additional columns

      Updating and merging data from different files

      Saving the file

      Troubleshooting

      ⚠️ Benefit users cannot be removed using a CSV file. Deletion must be done from the Benefit users view or from an individual user’s profile. Read the instructions for removing benefit users.

      Download CSV template

      Adding or updating benefit users should be done using the provided CSV template. Download the template or the current list of benefit users from the Benefit Users view and make changes to the downloaded file.

      How to download the CSV Template:

      1. Go to the Benefit users view.

      2. Click the “Import using a CSV File” button.

      3. Download the CSV file. If you have not previously added benefit users, you will see an option to “Download CSV template”. If benefit users have already been added, the option will be “Download beneficiaries”.

      4. Open the file from your computer’s downloads folder.


      Add or update data in the CSV file

      Adding or updating benefit users must be done using the CSV template. The downloaded file includes columns based on your company’s settings.

      Instructions for Filling in the CSV File:

      • Always make edits in the downloaded template or ensure that your file’s columns match the SmartumPlus system structure.

      • Add each benefit user on a separate row.

      • Use a semicolon (;) or a comma (,) as a delimiter.
        Example: name@example.com;100.00 or name@example.com,100.00

      • Separate benefit groups with quotation marks (“ ”).
        Example: "Group Name 1","Group Name 2"

      Tip: You can use XLOOKUP to update data. Read more: XLOOKUP.

      Required Fields

      The downloaded CSV file includes both mandatory and optional fields, which may vary depending on your company's settings.

      Field name Required? Description
      email Required* User’s email address
      hr_id Optional Percentage of Smartum benefits
      benefit_percentage Required Employer’s HR-ID identifier
      phone_number Required* User’s phone number (if no email).
      first_name Optional User’s first name
      last_name Optional User’s last name.
      status Optional Indicates whether the benefit is activated.
      id 🔒 Required System-generated user ID
      category_... Optional Groups the benefit user belongs to
      metadata_... Optional Custom company-specific columns

      * Either email or phone number is required. If an email is not provided, a phone number is required to send notifications.

      ⚠️ id: The system-generated user identifier (e.g., empl_V7y245) is used to recognize and update users in the Smartum system. Do not modify this field.

      Additional columns

      You can add custom columns to the benefit users table for company-specific needs, such as cost center or office location. Sensitive or personal data unrelated to benefits should not be entered.

      How to Add Additional Columns:

      1. Go to the Benefit users view.

      2. Click the three-dot menu in the upper-right corner of the table.

      3. Enter a column name and save using the “Add custom column” button. The new column will now be visible in the table, in the CSV template, and on the user’s profile.

      4. Re-download the Benefit user list (CSV) to include the new column, labeled as metadata_(column name). You can now add data to this column.

      Updating or merging data from different files

      If you need to merge the downloaded benefit user list with other data, you can use XLOOKUP/VLOOKUP in Excel or Google Sheets. The XLOOKUP function fetches data from another table and links it to the selected file.

      Refer to your chosen spreadsheet software's official guide: Microsoft Excel XLOOKUP Guide or Google Sheets VLOOKUP Guide.

      ⚠️ Note! When merging data, pay special attention to the user ID (empl_V7y245), as this is the key identifier Smartum uses to recognize and update users. Do not modify this field.

      XLOOKUP Formula Structure

      Ensure that:

      • The column structure matches the SmartumPlus system.

      • Any extra rows or empty columns are removed to prevent errors.

      Formula for merging data:

      =XLOOKUP ( value ; reference column ; return column ; default return value ;exact match ; search option )

      Esimerkki: =XLOOKUP(A2; Smartum_2024!A:A; Smartum_2024!H:H; ""; 0; 1)

      • Value: The value to search for (e.g., email in the new file).
      • Reference column: The column where the lookup occurs (e.g., email in the old file).
      • Return column: The column containing the desired data (e.g., user ID in the old file).

      • Default return value: You can specify a default value (e.g., leave blank "").

      • Exact match: Set to 0 (exact match).

      • Search option: Set to 1 (search from first to last).

      Step-by-step instructions for merging data

      Example of merging data with the XLOOKUP function. You can also use other methods, such as VLOOKUP, depending on the spreadsheet software you are using and your needs.

      1. Download the current benefit users and ID identifiers from the service.

        • Navigate to the Benefit Users view and download the CSV list of current users, which includes ID identifiers (e.g., empl_V7y245).
        • Name the file clearly, such as “Smartum_old.csv”.
      2. Open both files in a spreadsheet program.
        • The new file contains the data you want to import into the service.
        • The old file contains the current benefit users and their ID identifiers
      3. Add a new column for ID data in the new file. Name the column “id”.
      4. Enter the XLOOKUP formula in the first cell of the ID column in the new file. Refer to the formula instructions.
      5. Copy the formula to all rows. Click on the corner of the ID column and drag the formula down to apply it to all benefit users.
      6. Check the data and clear incorrect values. If the function returns an error (e.g., #N/A!), ensure that the data is correct or clear the cell.

      7. Save the file as CSV UTF-8. Make sure the file is saved in CSV UTF-8 format.

      8. Upload the updated CSV back to the service. The system will check the file and notify you of any changes or errors.

      9. Update benefit users. Click the Update Benefit Users button to confirm the changes.

      Saving the File

      • Save the CSV file in the same format it was downloaded.

      • Ensure no extra characters (e.g., blank rows) remain.

      • Choose the correct delimiter (; or ,).

      • Re-upload the file to the service. The system will check the file and notify you of any changes or errors.

      Troubleshooting

      Errors when importing a CSV file can be caused by incorrect file formats, missing information, or invalid values. Below are the most common issues and their solutions.

      If an error occurs, the system will highlight the affected field. Review the information, correct any mistakes, and re-upload the file.

      Undo changes: If you notice errors after importing the file, you can revert individual benefit user updates using the Undo button. If multiple errors were introduced, you can cancel all recent changes from the order confirmation page using the Undo changes button.

      File saving issues

      ssues during file saving may prevent the CSV file from uploading successfully. Before re-uploading, check the following:

      • Incorrect file format: Ensure the file is saved as CSV UTF-8.

      • Column formatting errors: If the columns do not display correctly in the service, make sure you are using the correct delimiter (semicolon “;” or comma “,”).

      Issues with groups and custom columns

      If benefit groups or additional columns are not imported correctly, consider the following:

      • Group names do not match: Ensure that group names are spelled exactly as they appear in the service.

      • Group not found: Check that the column header follows the correct format (category_NAME).

      • Invalid group category: If the system cannot recognize the category, review the spelling and format (category_NAME).

      • New group cannot be added: Groups must first be created in the Groups view before they can be included in the CSV file.

      • Unable to assign groups to users: Double-check the group names and ensure multiple groups are separated using quotation marks (e.g., "group1", "group2").

      • Missing custom column: Custom columns must be added in the Benefit Users view before they will appear in the CSV file.

      Field-Specific Errors

      Certain errors in specific fields may prevent the file from being imported. Review the following before re-uploading:

      • Unnamed column: If an unknown column is detected, verify that all column headers are correct. Read the instructions for adding a new custom column.
      • Missing custom column key: If a custom column is not recognized, ensure it has been added to the system before uploading the file. Read the instructions for adding a new custom column.
      • Duplicate email addresses found: If a user with the same email or identifier already exists in the system, remove duplicate entries before re-uploading. If using XLOOKUP or VLOOKUP, verify that the formula references the correct columns and matches exact values (e.g., email addresses).
      • Incorrect email format: Ensure all email addresses are properly formatted and free of typos.
      • Missing user ID: The system-generated user ID (e.g., empl_V7y245) is required to identify and update benefit users. Do not modify this field.
      • Invalid phone number format: Use the correct international format, such as +358123456789.
      • Benefit percentage out of range: The value must be between 0 and 100.

      If you continue to experience issues despite following these instructions, contact our support team at tilaajat@smartum.fi.