Pass Traits for Users and Accounts with the API

You can pass in custom fields for accounts and users, which allow you to segment your ideas by types of users, MRR, personas, accounts etc... In this article, we will walk you through how to send in this data with our API. 

Before you Start
  • This guide is geared towards individuals who have some technical knowledge in the realm of API's, but aren't developers. 
  • If this is something that you need to do on a regular basis, you should consult with your engineering team to automate this process and reference our API documentation here.
  • If you're not used to working with API's, check out this article for how to import with a CSV file. 
Unsure what we mean by User and Accounts—check out these articles:

Getting Started with the UserVoice API

You can interact with our API in the UserVoice admin console. To get here, navigate to "Settings" - "Integrations" - "API console".

We also recommend using a third-party tool to interact with our API, such as Postman.

Alternatively, you can use the $BASH command "cURL" to post to our API in a terminal/command prompt, and snippets for this can be found in our API documentation.

To begin, you will need to create an API client as documented here.

Setting up Postman

Once you have created an API client, you can use the Postman application to interact with our API.

1) Install Postman (it's free):

2) Choose Post, Get, or Delete depending on what API endpoint you are calling. [You will most likely be using POST endpoints, as these are how you import custom fields, external accounts, and external users.]

3) Use your subdomain (i.e. to construct the endpoint URL. The remainder of the URL will vary depending on which endpoint you are using.

Configuring Headers in Postman

Content-Type and Accept will both be application/json.
For Host, use your correct UserVoice subdomain (
For Authorization, you will need to retrieve a Bearer Token from our API.
  • You can get the Bearer Token by opening the UserVoice admin console in a browser and looking at a list of suggestions.
  • Use your browser's 'Developer Tools' to view the network traffic. Anything with 'API' will contain the token in its headers. Chrome example: screenshot
  • The value of the Authorization header will expire every 30 minutes.
  • Alternatively, you can retrieve a bearer token for the Authorization header using the terminal/command prompt, see step 2 here: link

Here is a screenshot of a fully configured Postman API client: screenshot

Using command prompt to retrieve a bearer token

1) Obtain an API Key and Secret: screenshot
"Settings" - "Integrations" - "UserVoice API keys"

2) Enter this snippet into your command line interface [details may vary depending on your operating system/version]:

token=`curl https://[SUBDOMAIN] --data "grant_type=client_credentials;client_id=[API_KEY];client_secret=[API_SECRET]"`
echo $token

Create custom fields, external users, and accounts with the API

Custom fields

Custom fields allow you to customize the data you store for each external_user or external_account. Once a custom field is created, you can assign values for this field, and use those to segment ideas based on the supporter characteristics that are relevant to your business.

post /api/v2/admin/custom_fields

Here are the parameters to post to this endpoint, and all are required:

name: the name of the custom field
key: the unique key of the custom field - it must be prepended with cf_    
field_type: sets the different data types for a custom field  
boolean: true or false
timestamp: unix timestamp
string: a snippet of text (less than 255 characters)
text: a long block of text
number: a number
object_type: determines the kinds of objects in UserVoice the field can be applied to

Endpoint syntax: post /api/v2/admin/custom_fields

JSON body syntax example:

screenshot of an example call in the UserVoice API console
screenshot of an example call in Postman request headers and body.

External Accounts

The external account object contains traits about an account from your external system(s). The account is linked to one or more users, to allow segmentation of user ideas by supporters’ account traits.

post /api/v2/admin/external_accounts/import

Here are the fields, required ones are marked with an (*):

*external_id: unique ID in your system
mrr_cents: monthly recurring revenue
ltv_cents: lifetime value
external_created_at: Date-time format 
cf_customfieldkey: one of your custom field values

Endpoint syntax: post /api/v2/admin/external_accounts/import

JSON body syntax example:


screenshot of an example in the API console
screenshot of an example call in Postman request headers and body

External Users

The external user object stores user traits from your external system(s). This allows segmentation of user ideas based on user traits that are of interest to your business.

post /api/v2/admin/external_users/import

Here are the fields, required ones are marked with an (*)[note that external account information is required to pass an external user]:

****this is external account information, and only the the external_id is required****

Endpoint syntax: post /api/v2/admin/external_users/import

JSON body syntax example:

"account": {
,"external_id": "33",
"cf_organization": "UserVoice"
  "external_id": "245",
  "name":"Joey P"

Feedback and Knowledge Base