If you would like to evaluate Guides and Surveys, please reach out to a member of your account team or fill out this form to be connected with a Fullstory team member.
Who can use this feature?
- Part of Guides and Surveys, an add-on for Business, Advanced, and Enterprise plans.
- Requires an Admin, Architect, or Standard role to configure.
Guides and Surveys is in active development. Product functionality and documentation may change without notice.
Guides and Surveys lets you import user data before users engage with your content. Importing users is useful when you want to pre-load information such as names, tags, or segment assignments so that personalized experiences are ready from the first interaction.
In this article:
How to import users
To import users into Guides and Surveys:
- In Guides and Surveys, navigate to the Users section.
- Click the Imports button, then click Import Users.
- Review the file requirements in the modal. Download the Sample file if you need an example of the expected format.
- Attach your prepared file and click Import Users.
- The import may take a few minutes. Refresh the page to check the status.
- When the import is complete, a green Success status appears.
- Verify the imported users by navigating to the Users section.
Data requirements
Import files must be in CSV, XLS, or XLSX format, with a maximum file size of 200MB. To see a correctly formatted example, download the Sample file from the Import Users modal.
The file supports the columns described below. Only userId is required; all other columns are optional. Column names are case-sensitive and must match exactly as shown.
Tip: Make sure the userId value is entered correctly. It is the key identifier used to associate all other imported data with the correct user.
userId
Required. A unique identifier for the user. This value must match the userId you use when identifying users in Guides and Surveys.
- Format: String or number
-
Examples:
2,user123
segment
Optional. Sets whether the user is treated as a new or returning user for auto-segmentation purposes. If omitted, the user is classified as a returning user by default.
- Format: String — must be one of the accepted values exactly as written
-
Accepted values:
-
first_time_user— user is new (seen for the first time within the last 24 hours) -
returning_user— user has been seen before (default if not set)
-
-
Example:
first_time_user
For more on how auto-segmentation works, see Guides and Surveys - Segmenting Users.
tags
Optional. Assigns one or more tags to the user. Tags are key-value pairs used for segmentation and targeting. They can also be used to personalize content shown to that user — for example, displaying a user's name or role in a tour step.
-
Format: Key-value pairs using a colon (
:) to separate the key from the value. Use a comma (,) with no spaces to separate multiple pairs. -
Examples:
- Single tag:
Role:admin - Multiple tags:
Role:admin,age:23
- Single tag:
To learn how tags can personalize content in tours, banners, and other guides, see Guides and Surveys - Personalizing Content.
firstName
Optional. The user's first name. This value is stored on the user's profile.
- Format: Plain text string
-
Example:
Joey
lastName
Optional. The user's last name. This value is stored on the user's profile.
- Format: Plain text string
-
Example:
Tribbiani
signUpAt
Optional. The date and time the user registered. This value is stored on the user's profile and can help you understand when users joined.
- Format: ISO-8601 datetime string, including timezone offset
-
Examples:
- With offset:
2023-09-09T15:45:00+03:30 - UTC (Z suffix):
2023-09-09T15:45:00Z
- With offset:
customSegments
Optional. Assigns the user to one or more custom segments that you have already created in Guides and Surveys. Custom segments must exist before you can import users into them.
Note: Custom segments can only be assigned to new users during import. Existing users will not have their custom segment updated by an import.
- Format: Comma-separated list of segment name strings (no spaces around commas)
-
Example:
segment_name_1_1,segment_name_1_2 - Where to find the segment name: Navigate to Users > Segments and click Instructions next to a segment. Note the "segment value for importing" in the modal that appears.
For more on creating and managing custom segments, see Guides and Surveys - Segmenting Users.
Frequently Asked Questions
Can I import customSegments for users that already exist in Guides and Surveys?
No. The customSegments column only takes effect for new users. If a userId already exists in Guides and Surveys, the customSegments value in the import file will not be applied to that user.
Where do I find the segment value to use in the customSegments column?
Navigate to Users > Segments and click Instructions next to the segment you want to use. The "segment value for importing" shown in the modal is the value to enter in the customSegments column of your file.