UserVoice API NPS Import Tutorial

api_key_create.png

api_key_dialog.png

ImportNPS.rb

require 'net/http'
require 'net/https'
require 'json'

# Change 'feedback' to the name of your UserVoice subdomain (leaving the quotes)
subdomain = "feedback"
# Change "xxxe8ae9c6a3c039" to the bearer token you received in step 1 (leaving the quotes)
token = "xxxe8ae9c6a3c039"

# Put your data into a json object with fields matching this example
# The rating and the user email fields are required
rating = {
  "rating": "10",   # Required
  "prompt": "How likely would you be to recommend UserVoice to your colleagues?",
  "body": "UserVoice is great, it helps me understand our customers needs perfectly!",
  "date": "2018-10-01T14:33:24.614Z",
  "user": {
    "email": "carter.jackson@gmail.com",   # Required
    "name": "Carter Jackson"
  }
}

uri = URI.parse("https://#{subdomain}.uservoice.com/api/v2/admin/nps_ratings")

response = Net::HTTP.post(uri, rating.to_json, "Content-Type" => "application/json", "Authorization" => "Bearer #{token}")
body = JSON.parse(response.body)
if response.code == "200"
  puts "Success"
  puts "Response Code: 200"
  puts "id: #{ body['nps_ratings'][0]['id'] }"
else
  puts "Failure"
  puts "Response Code: #{ response.code }"
  if response.code == '422'
    puts "Missing #{ body['errors'].keys.first }"
  elsif response.code == '401'
    puts "Invalid API token"
  end
end

nps_tutorial.md

How to import NPS ratings into UserVoice (w/ Ruby)

1. Getting an API Token

Any interaction with the UserVoice API requires a trusted API client. You can create one from your UserVoice Admin Console in Settings → Integrations → UserVoice API keys.

Enter a name for the API Client, it is good practice to use a name that will help you keep track of where the token will be used (e.g Zapier Integration). Leave the "APPLICATION URL" and "CALLBACK URL" text fields blank, and make sure the “Trusted” checkbox is checked. Then click the button labelled "Add API key" to create the client.

Find your client by name in the list and click the "Create" link to display the token you will use to access the access the API.

A dialog will appear with your token.

(Note that keys shown here are dummy values)

Copy this value and replace the placehold value 'xxxe8ae9c6a3c039' with your copied token in the next step.

Beware: You should never store trusted client credentials in an insecure environment (for example: in your client-side JavaScript or a public source code repository). Trusted clients have full access to perform the same actions admins do, including deleting content.

Note: The UserVoice API requires all calls to be made over HTTPS.

2. Creating the Script

Create a Ruby file with the following, substituting your own data at the top. This example is in Ruby, however you can use any language of your choice to achieve the same result.

require 'net/http'
require 'net/https'
require 'json'

# Change 'feedback' to the name of your UserVoice subdomain (leaving the quotes)
subdomain = "feedback"
# Change "xxxe8ae9c6a3c039" to the bearer token you received in step 1 (leaving the quotes)
token = "48403e04fdbbee26"

# Put your data into a json object with fields matching this example
# The rating and the user email fields are required
rating = {
  "rating": "10",   # Required
  "prompt": "How likely would you be to recommend UserVoice to your colleagues?",
  "body": "I named my first child UserVoice!",
  "date": "2018-10-01T14:33:24.614Z",
  "user": {
    "email": "carter.jackson@gmail.com",   # Required
    "name": "Carter Jackson"
  }
}

uri = URI.parse("https://#{subdomain}.uservoice.com/api/v2/admin/nps_ratings")

response = Net::HTTP.post(uri, rating.to_json, "Content-Type" => "application/json", "Authorization" => "Bearer #{token}")
body = JSON.parse(response.body)
if response.code == "200"
  puts "Success"
  puts "Response Code: 200"
  puts "id: #{ body['nps_ratings'][0]['id'] }"
else
  puts "Failure"
  puts "Response Code: #{ response.code }"
  if response.code == '422'
    puts "Missing #{ body['errors'].keys.first }"
  elsif response.code == '401'
    puts "Invalid API token"
  end
end

3. Running the Script

You can now run the script! It should import your NPS rating into UserVoice for later use. The output will show the status of the import.

For a successful import, you will see the following output containing the ID of your new NPS rating:

Success
Response Code: 200
id: 194823

For an unsuccessful import, you will see output showing what went wrong.

The following would indicate that the record did not include a rating:

Failure
Response Code: 422
Missing rating

If your API token is missing or incorrect, the response will resemble the following:

Failure
Response Code: 401
Invalid API token

Additional Information

For more complete documentation of the NPS endpoint, see https://developer.uservoice.com/docs/api/v2/reference/#/nps_ratings_1?q=nps