Use Postman to pass fields for user and accounts

If you're on our Scale Plan (the latest version of our Product Management platform), you can import custom fields for accounts and users, which allow you to segment your feedback by types of users, MRR, personas, accounts etc... In this article, we will walk you through how to import this data with our API. 

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.

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):http://www.getpostman.com/

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. xxxxx.uservoice.com) 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 (xyz.uservoice.com)
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].uservoice.com/api/v2/oauth/token --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 feedback 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
external_users
external_accounts

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

JSON body syntax example:
{"name":"Organization","key":"cf_org","field_type":"string","object_type":"external_accounts"}

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 feedback 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
name
plan
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:

{
"accounts":[
{
"external_id":"34",
"name":"foo",
"plan":"bar",
"mrr_cents":100,
"ltv_cents":1000,
"external_created_at":"2017-01-24T21:52:19Z",
"cf_company":"UserVoice"
}
]}

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 feedback 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]:

*external_id  
*email  
user_id    
name    
external_created_at    
ip    
type    
last_seen_at    
seen_days    
cf_usercustomfieldkey
       
****this is external account information, and only the the external_id is required****
*external_id    
name  
plan
mrr_cents    
ltv_cents  
external_created_at    
cf_accountcustomfieldkey

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

JSON body syntax example:

{
"users":[
{
"account": {
"name":"UV,inc."
,"external_id": "33",
"cf_organization": "UserVoice"
},
  "email":"jmpe@test_example.com",
  "external_id": "245",
  "name":"Joey P"
    }]}

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




Feedback and Knowledge Base