This is a guide for getting starting with passing in standard and custom traits for users and accounts into UserVoice. Unsure what this feature is? Check out our getting started guide here.
UserVoice User: This is the profile that's created for a user on your UserVoice account automatically when they log in with our default login, interact with the widget or authenticate with SSO. E.g. your end users that are providing feedback.
External Users: Imported user information from your database. Always mapped to the UserVoice user based on the email or UserVoice ID. Required if you want to connect a UserVoice User to an External Account. You can have multiple External Users connected to one UserVoice user.
External Accounts: An Account is a group of users from the same organization. You pass in external accounts, and then connect them to UserVoice users with an external user.
Standard fields are preset traits that you can use out of the box. External_ID's are always required, but for the other fields you can pick and choose what you need.
Standard User Traits
- External_ID: Required
- Email: Required
- Name: Only seen by admins, and does not update their UserVoice display name
- Created_At: Defaults to the first time you passed in the external user. This field is used to determine auto-prompts for NPS widget.
- IP: Defaults to the IP we have for the user, but you can pass your own. This is used to set a location for the user.
- Type: Could be admin, owner, developer, end-user, etc.
- External Account ID: Required to connect the external user to an external account.
Standard Account Traits
- External_ID: Required to create an account
- Name: Account name
- Plan: Plan name
- MRR: Monthly recurring revenue (or the revenue type that is relevant to your business). If you pass revenue, we can then aggregate the revenue of accounts that have voted for an idea.
- LTV: Lifetime value of the account.
- Created_At: Defaults to when the account object was first created in our system.
Can I connect a UserVoice user to multiple accounts? Yes, you can. You will need to pass in an external user (with its own unique ID) for each account. They are all mapped to the same UserVoice user via email address.
Is an External User Required to connect a UserVoice user to an account? Yes. If you want to connect a UserVoice user to an account, you must pass an external user for that UserVoice user.
Custom traits are traits you create to pass through your own custom data on users and accounts. You have five types of custom traits you can create and pass data for.
- Text: Single line Text, up to 128 characters
- Multi-Line Text: Up to 10,000 characters
- Number: Whole or decimal numbers 15 digits
- Date & Time: RFC3339 timestamp OR YYYY-MM-DD HH:MM:SS
- Boolean: true or false
- URL: Will display a link, must be valid URL format, e.g. http://www.example.com
Create your Custom Traits Fields
Getting Started: If you are passing in custom traits, you must set up the fields before passing through any data. You can do this two ways.
- User's Page: Click the "voters" icon in the left-hand menu -> Click the "gear" icon to the right -> You'll see the option to create user and account fields
Staging your data to add to UserVoice
- List out all User and Account traits you would like to see in UserVoice, using the field names you see in your database.
- Match up as many fields as possible to fields that are already found in UserVoice (standard traits). See this article for more information.
- If you have field remaining, these will be your custom fields. Name them using the naming convention 'cf_your_custom_field'.
- Add the datatype to each custom field (from the list of accepted data types).
Now that you've created the fields, we'll walk you through your options for passing traits in for users and accounts.
Import Traits from a CSVWith our CSV import feature, you can import your user and account traits using a spreadsheet. You may get your source data from a salesforce export, your product database, etc.
Import Traits with our Sync Service
Pass in Traits with the APIData sent in via the API will show immediately in the UI. This is the best long-term solution for keeping external user and account information up-to-date.
Getting Started: You will need engineering resources on your end to set this up with the API. We do have this guide for using Postman if you're awaiting engineering resources.
- Guide for Importing Users and Accounts with the API
- External User API Reference
- External Account API Reference
- User and Account traits passed via the widget do not show in the UI until the user interacts with your UserVoice site—votes, comments, creates an idea, sends a message, or gives an NPS rating.
- The widget only supports passing one user profile and associated account. If you need to pass in multiple external users or accounts, you will need to use the API or the CSV import.
Automatically Generated Accounts by Email Domain
- External accounts will be automatically generated and populate the Accounts grid in UserVoice as external users emails are added to UserVoice. This will only happen for accounts with no existing Account data. If you wish to use this feature, please contact our support team by clicking "Support" in the bottom-right corner of your window.
- Since these accounts are generated based on user email domains, each account’s name will match the email domain that generated it minus the “@” symbol.
- External ID of the account will always be the full domain including the @ symbol. For example, External ID: @acme.com.
- Per account, the number of users will be updated as feedback is received by users from that email domain.
- Ideas and features counts on these external accounts will be updated normally as user feedback is associated to ideas and features. You can use the CSV import documented above to update Account data that is generated from email domains.
- On the Ideas and Features grids, reach column for accounts will be automatically updated as these accounts are generated.
- External Accounts will not be created for users with email domains from commercial email providers. A list of those email providers can be found here.
Q: How do I unlink a user from an account?
A: You will either need to delete the external user, or pass null for the external_account_id for the external user.