• Home
• Users & Segments
• Importing Data

Userlist allows you to import user and company data via CSV files. This is helpful for:

• Bulk-adding new users or companies
• Updating existing uses or companies (including situations when you only need to add or update specific properties)
• Migrating subscriber data from other systems

For more complex data structures, like managing relationships between users and companies, we recommend using the Userlist API or Segment integration.

Preparing your CSV file

Before starting your import, make sure your CSV file is prepared correctly. Follow these requirements:

• Use UTF-8 encoding for your CSV file
• Include a header row with property names
• Use commas (,) as delimiters
• Enclose fields containing commas in double quotes (")

Sample CSV structure

1
2
3
identifier,email,signed_up_at,plan,is_active
user123,john@example.com,2023-06-15T14:30:00.000Z,premium,true
user456,jane@example.com,2023-06-16T09:15:00.000Z,basic,false

Required fields

Users. Provide at least an identifier or an email. Email isn’t the default unique identifier but can be set as one for marketing leads.

Companies. The identifier is required for all companies.

Missing fields

You don't need to include every property in your CSV — just the ones you want to add or update. If you leave out certain properties in the CSV, they will remain unchanged in the existing records.

Opt-in status

Imported users are automatically opted in. Even with double opt-in enabled, users will be treated as already opted in and won’t receive a confirmation email.

Custom properties

No special naming conventions are required. We will automatically map column names to system properties (such as email or identifier) and existing custom properties, and create new custom properties for other columns. You can also adjust column mapping during the import (see steps below), and even type new desired property names.

Formatting data

Use these formatting guidelines to avoid errors:

• Custom properties can use any format, and their type will be inferred.
• For date fields we recommend using the ISO 8601 format: YYYY-MM-DDTHH:MM:SS+TZ (e.g., 2023-06-15T14:30:00.000Z.) If no timezone is provided, Userlist will assume UTC.

Importing users

To import users, navigate to the Users page in your Userlist account. Click the Import button at the top right of the page.

Upload your CSV file using this dialog:

Review and adjust column mappings as needed:

Click Start to process the data.

Imports are processed in the background. You’ll receive an email notification once the import is complete.

User matching

User records are matched as follows:

• If a matching identifier is found, the record is updated
• If no matching identifier is found, we move on to matching by email
• If a matching email is found, the record is updated
• If no match is found by either identifier or email, a new user record is created

Importing companies

To import companies:

1. Go to the Companies page in Userlist. Click the Import button at the top right of the page.
2. Upload your CSV file.
3. Review and adjust column mappings as needed.
4. Click Import to process the data.

Imports are processed in the background. You’ll receive an email notification once the import is complete.

Company matching

Company records are matched as follows:

• If a matching identifier is found, the existing company record is updated
• If no match is found by identifier, a new company record is created