Formatting your user data files for manual upload or SFTP

Table of Contents:

Adding data to your template
User Scope: Who needs to be included in each upload?
Attribute scope: What user data do I need to include in the file?
General formatting requirements
Using the upload preview in Leapsome
Troubleshooting and Frequently Asked Questions

Our user data import is a great and simple way to add, update, and deactivate user profiles in bulk. For this, you can either use a manual file upload or automate this process through SFTP. Both SFTP and the manual import use a template to process your team’s data. This article shows you which data you should include in the file, and how to format it to ensure a successful import. You can learn more about setting up the SFTP integration in this article.

In a nutshell

• Use the customized template and don’t modify the headers/columns.
• If possible, include all active and deactivated users in the file.
• Include the correct status attribute for all users.
• Ensure you use the correct unique identifier.
• Strictly follow the file and attribute formatting specified below.
• Where no values are present, leave fields empty instead of using placeholders.
• Check the data preview in Leapsome before submitting your upload.

Adding data to your template

To import your users successfully, you have to use our template. You can download a template customized to your account settings from 'Company' > 'Employees' > 'Actions' > 'Export users'. The first line of the template contains the headers, which represent the different user attributes you can update in Leapsome. Your template is unique in a way that also the custom attributes you may have created in Leapsome will show as headers in the template. The rows below the headers will include the current data in Leapsome for each attribute for all users already added to the platform.

User Scope: Who needs to be included in each upload?

We recommend always including a full list of active and deactivated employees, instead of just those who had recent changes.

• A manager relationship will only be created if the manager's email and a user with a matching email address are provided in the same document.
• Also include deactivated users. Removing users from the file will not remove them from Leapsome automatically; including them with their new status will.

User Creation, Invitation, and Deactivation

You can easily activate and deactivate user profiles using our data import. Leapsome handles this using the 'Status' attribute.

To activate users, set the users’ status to 'active'. To deactivate users, set their status to 'deactivated'.

If you are uploading users for the first time, please make sure to set the users’ status to 'active'. This import will then only ‘create’ the profiles for your colleagues. Only once you have triggered their invitation in Leapsome will they be able to activate their accounts and access the platform.

User invitations can be sent manually or automatically. You can learn more about it here.

If the setting 'Automatically send Leapsome invite emails to provisioned employees' is OFF, but the SFTP file lists the employee status as ‘active’, then an invite email will not be sent to those employees. You can trigger the invites manually at a later time. SFTP file uploads will only have employee statuses in one of two states: ‘active’ or ‘deactivated’. If you send a file with 'active' users, this will trigger the accounts to be:

• 'Created' (if auto-invites are off) - you can invite them manually later
• 'Invited' (if auto-invites are on) - employees will receive an invitation email and will be able to log in

As by default Leapsome deactivates by status, please make sure that deactivated users are also included in your file. Alternatively, if you are not (!) using SFTP or another HRIS intergration, you can allow Leapsome to automatically deactivate users as soon as their Termination date has passed. You can enable this option under 'Settings' > 'Company' > 'Basic settings'. If you are using any HRIS integration or SFTP, please do not use this option, since in this case 'Status' should be used exclusively to deactivate users, to avoid data conflicts. 

Attribute scope: What user data do I need to include in the file?

Aside from a few mandatory attributes, you can decide which attributes and values you want to populate with data using the file upload. Depending on the functions you may want to use within Leapsome, we recommend adding specific non-mandatory attributes to your user’s profiles. This table gives you an overview of which attributes can be imported via Excel upload/SFTP and what the data can be used for in Leapsome.

Working with the file headers

Leapsome uses the headers of the template to map the user data to the right fields in Leapsome - issues with the headers thus may lead to incorrect uploads or cause the import to fail altogether.

• Do not change the spelling of the headers.
• Do not remove any headers from your template - Simply leave unwanted columns empty instead of deleting the whole column.
• Please do not use placeholders like 'N/A' or '-' if you do not want to enter a value as these may show up in Leapsome or may cause issues during the upload.

Mandatory attributes

Leapsome requires the 'Email / Username' and 'Status' fields to be populated for the upload or import to succeed.

• 'Email / Username' is the primary unique identifier. External ID is the backup identifier used to handle email changes.
• 'Status' is used for the automated (de)activation of users. Indicate this as ‘active’ for everyone who should have a Leapsome profile.

Attributes requiring unique values

Some attributes require unique values for the import to succeed without issues. If these values are not unique, the upload won’t work or may lead to unwanted results like duplicated user profiles.

• Email and External ID need to be unique.
• If you do not want to populate the External ID, just leave it empty. Do not add placeholders like “N/A” or “-”, since these are not unique per user.
• To match existing users, Leapsome uses three different attributes as unique identifiers: Leapsome ID, External ID, and Email. If the upload contains data for all three attributes, the Leapsome ID takes precedence, followed by the Email and External ID.

Removing Data using an import

• By default, removing data from your file will not remove the respective information from Leapsome.
• For data fields that only contain a single value, like 'Location', replacing the value in your file will automatically remove the old and add the new value to the user’s Leapsome profile.
• The ‘Teams’ field can by default hold more than one value. Using the upload, Leapsome by default only adds additional teams on top of the previous selection and does not remove any teams. You have the option to automatically replace all teams with data from the most recent import/upload. For manual uploads, this option shows when performing the upload. For SFTP imports, you can find this option in the SFTP settings within Leapsome.
• If you wish to remove values for your users without adding a replacement, you can do so by replacing the value with _reset to delete any information Leapsome currently stores in that field. Please note that this currently does not work for Custom Attributes.

General formatting requirements

Data field formatting

When creating your file, please make sure to stick to our required field formatting as indicated in the headers to make sure all data gets imported successfully.

• Attributes supporting multiple values:
  • Some fields support adding multiple values, such as ‘Teams’, or ‘Additional managers’.
  • There, please use semicolons to separate values. If you use semicolons also as separators in a CSV file, make sure to mark values containing semicolons as text (e.g., by using “”).
• Date fields:
  • Dates need to be uploaded in DD-MM-YYYY format. Diverting from this format in any way may lead to incorrect values being uploaded.
  • In Excel, make sure to format dates as ‘Text’ to ensure the format is saved and imported exactly in this format.

File formatting: Excel

Leapsome supports file uploads in .xls and .xlsx format, which is an easy way to create your upload file without the need to change its format to e.g., CSV.

• Make sure to format all values within your sheet as ‘Text’ as opposed to ‘Standard’, to make sure the specific formats like dates are not ignored/transformed during import, which may result in incorrect data showing in Leapsome.
• Please keep in mind that Leapsome will only read data within the first tab within your file.

File formatting: CSV

Using CSV format should only be done in case .xlsx or .xls are not an option, since it offers a higher risk for formatting errors.

• Defining separators and marking text:
  • If possible, use pipes “|” as separators to prevent conflicts or incorrect imports (we use commas in our headers and semicolons as separators for multi-value attributes).
  • If you use commas or semicolons as separators, please ensure to add text identifiers like “”.
• Ensuring special characters are saved properly:
  • If, e.g., employees’ names contain special characters, these may not be saved properly within a regular .csv file.
  • To avoid this, please make sure you use a UTF-16 encoded CSV file, or in case you are using a UTF-8 encoded one, to save it 'with encoding' or 'with BOM.'

Using the upload preview in Leapsome

To check that your file is ready, you can preview the upload in Leapsome before confirming. Please carefully check that the values shown match the formatting you expect. If there are issues in your file, the preview will provide an error message including the rows you need to double-check.

You can also do this step if you plan to implement SFTP. Simply discard the upload by clicking 'x' after you check the preview.

Troubleshooting and Frequently Asked Questions

I made a mistake in my upload. Can I quickly restore the previous version of my users' data or undo the import?

Leapsome does not have an option to undo an import. To fix any mistakes, best correct your user data file and perform another upload. If data needs to be removed, you can replace the incorrect data with _reset to remove the data from users' profiles with the next upload (except for Custom Attributes).

Is there a way to spot issues with the file before the changes are live in Leapsome?

For manual file uploads, Leapsome will always show you a preview of your data to check whether the uploaded data shows in the right places.

For SFTP there is no such preview since the upload happens automatically. If there are problems with your SFTP connection or in case the upload failed, you will see a red error message in your SFTP settings and Employee list in Leapsome.

My file seems not to be processed at all

• Check if your file is in Excel or CSV format.
• Make sure your data is within the first (and ideally only) tab of the file.
• Ensure all headers are included in your file and do not differ from our template.
• Check if 'Email / Username' and 'Status' are populated - these are required to perform the upload.
• Check if all values that should be unique are unique or left empty.

Data was uploaded but shows in the wrong place

• Ensure all headers were included in your file and sent in the right format. You can pull an export from your Employee list in Leapsome to compare it to your file.
• If you use a CSV file, ensure you use pipes '|' as separators or use text identifiers for all values in combination with comma or semicolon-separators.

Users were not deactivated

• Ensure the to-be-deactivated users were included in your file - ideally, you send a file with all (!) of your colleagues, both active and deactivated with each import.

Users that are supposed to be active were deactivated

• Please check that the 'Termination Date' for the affected user is not set and their 'Status' is set to 'Active.'
• In the Employee List in Leapsome, make sure that there is no (previously or manually added) Termination Date within that user's profile, or remove it if needed.

A manager change was ignored

• Ensure you included the new manager's email address in the 'manager' field for the affected employee.
• Ensure that the manager in question is also included as a user in your upload file. Ideally, always send a full list of employees with each upload to prevent this situation.