Importing Users and Accounts with UserVoice API

Object model overview

UserVoice users

A UserVoice user is anyone who can sign into your UserVoice account, either as an admin, contributor, or end user. It can also represent anyone who has given feedback that has been collected in your UserVoice account, without having actually signed in. This will often be the case for feedback that has been imported or captured using the contributor sidebar. We require every UserVoice user to have a unique email address within your account.

External users

An external user is the representation in UserVoice of a user record in your own application or customer database. It is a place to store data that is unrelated to the functioning of your UserVoice portal, but which you want to import into UserVoice to enhance analysis of your feedback. For example, the number of ideas a user supports is a property of their UserVoice user, but what type of user they are in your application is a property of their external user.

Every external user will be associated with a UserVoice user object, although this user may have never signed into UserVoice or given feedback. In many cases a UserVoice user will be associated with a single external user, and they will be presented as a single record. However, it is also possible to have multiple external users connected to one UserVoice user. This is necessary to handle two scenarios: you have users that are associated with multiple accounts, or you allow multiple users to have the same email address.

When an external user is created, it will be associated to the UserVoice user with the same email address. If there is no matching UserVoice user then one will be created. (Creating a UserVoice user is necessary for our record keeping. We will not send a notification to the user’s email address that they have a new UserVoice account.) If you later update the email address on an external user it will remain associated with the UserVoice user it was originally attached to, but you can manually set the UserVoice user by ID if you need to.

external users can be configured to have custom fields, which you can then use to segment the feedback you receive by the properties of the users associated with that feedback.

external users are required to have an assigned ID so that they can be reliably identified if a user’s email address is changed. If you do not have an ID for the user you can simply pass their email address as the ID.

An external user can optionally be associated with an external account.

External accounts

An external account (simply called an Account in the Admin Console) represents a financial relationship between you and your customer. It also functions as a way of grouping users together and assigning properties to the group. An external account can be associated with many external users, thus creating a many-to-many relationship between external accounts and UserVoice users.

external accounts have two built-in financial fields: MRR (monthly recurring revenue) and LTV (lifetime value). MRR is aggregated in several places in the Admin Console as a useful way to see how much money your feedback represents.

external accounts should be assigned an ID so that the relationship between external users and external accounts can be established. The one exception to this is that the external account ID is allowed to be null if it is embedded inside an external user record on import, but external accounts created in this way will not be able to be associated with any other external user. This is useful if you do not need to ever associate multiple users to an account, but still want to set MRR and LTV for your users.

external accounts can also have custom fields, which can be used for further segmentation of your feedback data. This is especially useful in B2B scenarios.

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 grid in the UserVoice Admin Console. It accepts up to 1000 external users per call, and each one can also embed an associated external account. It supports setting custom fields on the external user and on the external account. The semantics of this endpoint are identical to uploading an import file on the users grid in the Admin Console. 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 bulk_identify endpoint.

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 grid. It accepts up to 1000 external accounts per call, and supports setting custom fields. New external accounts created in this way will immediately show up on the accounts grid.

POST /api/v2/admin/bulk_identify

This endpoint is asynchronous. It will enqueue your external user and external account data to be saved and return very quickly. Furthermore, this data will not be immediately imported into your users grid. Updates to external users and external accounts that already appear in the Admin Console will be applied as quickly as they can be processed. However, new records we be stored in a separate data store until they give feedback. They will appear in your users grid once they create an idea, support an existing idea, or leave a comment. This is useful when you want to passively capture metadata about your users but you don’t want to overwhelm your users and accounts grids with data that is not connected to any feedback.

The bulk_identify endpoint uses the same mechanics as identifying users through the UserVoice widget embed code, but it does not currently support custom fields. It accepts up to 1000 external users per call, with an optional embedded external account per user.

GET /api/v2/admin/users

This endpoint will allow you to retrieve a list of all the UserVoice users in your account, just like the users grid 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. 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.

Common scenarios

Scenario: You are sending feedback data (suggestions, requests, NPS ratings, etc) through the API and you also want to send user info

Use the external users import endpoint to upload the user info. If you don’t know the ID of the UserVoice user, the response from this call will provide it to you. (And it will create a UserVoice user for the provided email address if it doesn’t exist.)

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:

  1. If you are using the UserVoice widget to collect feedback, configure it to send data about the user in the widget embed code. 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 installed, but may become stale if they use your app infrequently.

  2. 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 custom fields and account data. 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.

  3. Send all of your users to the bulk_identify endpoint in batches. The latest external user data for these users will appear in your Admin Console once feedback is captured from them. To keep the data up-to-date, send your user data to the bulk_identify endpoint whenever it is modified in your own database. You should batch these updates to reduce the number of API calls and avoid being rate limited.

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 MRR and LTV values for each user.

Scenario: You want to passively collect user info, such as software version and location data in a native client such as a mobile app

In this situation it is not appropriate to send the data to the external users import endpoint. It is likely that you will produce a large number of API calls with mostly duplicate information, especially if you send this data every time a user launches your app. Use the bulk_identify endpoint, which is designed to handle higher volumes of traffic.

Scenario: You want to keep your accounts in UserVoice up-to-date with your own account database or Salesforce 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.