Not included in your plan? Want to learn more about the benefits? Leave us a message! If you're viewing this on our Help Center, click the Support bubble in the lower-right of this page.
If you use Salesforce, we highly recommend syncing your Salesforce data using our Salesforce Connector. The connector will automatically keep your data up to date.
Note: If you have setup the connector, you will not be able to import traits via CSV.
If you use HubSpot or Dynamics we recommend taking advantage of our Sync Service. The sync is a managed service that will automatically sync data from these systems for you.
If you want to import data from any other system, continue with this guide. This is a guide for importing user and account traits with our Admin API. If you're not familiar with user and account traits in UserVoice, be sure to check out our getting started guide here.
This article should be shared with your Engineering team.
Passing Traits with the API
This is the best long-term solution for keeping external user and account information up-to-date.
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 fields to fields that found in UserVoice. See this article for more information.
Now that you've created the fields, we'll walk you through your options for passing traits in for users and accounts.
Getting Started
API Endpoints
POST /api/v2/admin/external_users/import
This is the transactional endpoint for importing external users. It will not return until the records have been written to the database, and all users imported in this way will immediately show up in the users area, in the UserVoice Admin Console. It accepts up to 1000 external users per call, and each one can also embed an associated external account. This endpoint should not be used to send data to UserVoice every time a user uses your app. If you want to collect data about users in a mobile or desktop environment, you should use the Identify object.
POST /api/v2/admin/external_accounts/import
This is the transactional endpoint for importing external accounts. It is very similar to the external users import endpoint, and works the same as the import function on the accounts area. It accepts up to 1000 external accounts per call. New external accounts created in this way will immediately show up on the accounts grid.
GET /api/v2/admin/users
This endpoint will allow you to retrieve a list of all the UserVoice users in your instace, just like the users area in the Admin Console. This will return up to 100 UserVoice users at a time, depending on the per_page parameter. You can use the page parameter to page through all the users in your account or use the cursor
. Deep paging will degrade in performance, so this is only recommended if you have fewer than 10k UserVoice users in your account. You can also retrieve the external users and external accounts associated with a page of UserVoice users by using the includes
parameter. Read more about pagination and side-loading here on our developer site.
Common scenarios
Scenario: You want to import your user database into UserVoice, and keep it up-to-date
Think about whether it will be useful to have all of your users listed in the UserVoice Admin Console. In most cases, only a subset of your users will give feedback. Consider the following strategies:
-
If you are using the UserVoice widget to collect ideas, configure it to send data about the user with the widget Identify object. This way, you will always have fresh user data at the time the user gives feedback. There is nothing you need to do to keep this data up-to-date. Their data will be updated passively whenever they use your app that has the widget SDK installed, but may become stale if they use your app infrequently.
-
Query the users endpoint to find all the users that exist in your UserVoice account and then use the external users import endpoint to set their traits. This approach is only viable for accounts with less than 10k UserVoice users. To keep your user data up-to-date, simply run this process again periodically.
In any case, you can optionally provide current account information for one associated external account when you upload each external user. For B2B scenarios, this can be a useful way of passively keeping accounts updated. For consumer applications, you can use the embedded external account to send revenue values for each user.
Scenario: You want to keep your accounts in UserVoice up-to-date with your own account database or CRM data
Use the external accounts import endpoint to create or update your accounts in UserVoice. If possible, send them in batches of up to 1000 external accounts.
Common Questions
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.