Getting Started with the UserVoice API

The UserVoice API exposes the core end-user and admin functionality of UserVoice to make it easy for you to build client applications or integrations with your own systems.

1. Create an API client

Before you can make any requests you need to create an API client. Go to your UserVoice Admin Console.

Go to Settings → Integrations → UserVoice API, and click Add API Client.

Enter a name for the API Client and then decide if you want the client to be trusted or not. Some endpoints require a trusted client. However, DO NOT check this if your API Key will be stored in an insecure environment (for example: a Javascript client application that end-users download)!

2. Install the SDK of your choice

To make one of the requests in our API Reference, you can use one of our API clients depending on the programming language you plan to use.

The UserVoice C# library can be installed using NuGet, the package manager. Follow the instructions in NuGet Gallery and run this command in Package Manager Console:

1
Install-Package UserVoice

Place the following in your pom.xml when using Maven:

1
2
3
4
5
<dependency>
  <groupId>com.uservoice</groupId>
  <artifactId>uservoice-java</artifactId>
  <version>0.0.2</version>
</dependency>

Remember to check the latest version!

Then fetch the package with all the dependencies by running:

1
mvn clean install

The PHP library uses Composer as a package manager and requires two extensions to be installed and then loaded in php.ini:

After installing OAuth and mcrypt, make sure the extensions are loaded from your php.ini:

1
2
extension=oauth.so
extension=mcrypt.so

Composer requires you to create a dependency file composer.json, where you include uservoice/uservoice as a dependency:

1
2
3
4
5
{
  "require": {
    "uservoice/uservoice": ">=0.0.6"
  }
}

Now execute the dependency manager (installation) in your project root:

1
php composer.phar install
The command will create a directory “vendor” under the current working directory. The vendor contains the dependencies of uservoice/uservoice including the file autoload.php. It also makes sure the PHP5 extensions are available. The output should be something similar to this:
1
2
3
4
5
6
Loading composer repositories with package information
Installing dependencies from lock file
  - Installing uservoice/uservoice (v0.0.6)
    Downloading: 100%

Generating autoload files

Install the uservoice Python module from PyPI:

1
pip install uservoice

or download the latest release from PyPI, unpack it and use the setup.py method:

1
2
cd uservoice-vX.Y.Z
python setup.py install

Add this into your Gemfile:

1
gem 'uservoice-ruby'

And run Bundler:

1
bundle install

If you’re not using Bundler, you can install it gem for the SDK like this:

1
gem install uservoice-ruby

3. Make an API request

Alright! You’re almost ready. Now, Get the API KEY and API SECRET from the API client you created in step one and replace the corresponding subdomain name with your UserVoice subdomain.

Then you can make an example request as the account owner (provided that you created a Trusted client):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
using System;

namespace UserVoice
{
    class Example
    {
        static string SUBDOMAIN_NAME = "uservoice";
        static string API_KEY = "oQt2BaunWNuainc8BvZpAm";
        static string API_SECRET = "3yQMSoXBpAwuK3nYHR0wpY6opE341inL9a2HynGF2";

        public Example()
        {
            var client = new UserVoice.Client(SUBDOMAIN_NAME, API_KEY, API_SECRET);
            var owner = client.LoginAsOwner();
            var user = owner.Get("/api/v1/users/current")["user"];
            Console.WriteLine(user);
        }
        public static void Main()
        {
            new Example();
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
package com.uservoice;

import java.util.HashMap;
import java.util.Map;

import com.uservoice.Client;

import net.sf.json.JSONObject;

public class Example {
    public static final String SUBDOMAIN_NAME = "uservoice";
    public static final String API_KEY = "oQt2BaunWNuainc8BvZpAm";
    public static final String API_SECRET = "3yQMSoXBpAwuK3nYHR0wpY6opE341inL9a2HynGF2";

    public static void main(String[] args) {
        Client client = new Client(SUBDOMAIN_NAME, API_KEY, API_SECRET);
        Client owner = client.loginAsOwner();
        JSONObject user = owner.get("/api/v1/users/current").getJSONObject("user");
        System.out.println(user);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
<?php
    // If you haven't already, require autoload.php from the vendor directory
    include_once('vendor/autoload.php');

    $SUBDOMAIN_NAME = 'uservoice';
    $API_KEY = 'oQt2BaunWNuainc8BvZpAm';
    $API_SECRET = '3yQMSoXBpAwuK3nYHR0wpY6opE341inL9a2HynGF2';

    $client = new \UserVoice\Client($SUBDOMAIN_NAME, $API_KEY, $API_SECRET);
    $owner = $client->login_as_owner();
    $user = $owner->get_object("/api/v1/users/current.json");
    print_r($user);
?>
1
2
3
4
5
6
7
8
9
10
import uservoice

SUBDOMAIN_NAME = 'uservoice'
API_KEY = 'oQt2BaunWNuainc8BvZpAm'
API_SECRET = '3yQMSoXBpAwuK3nYHR0wpY6opE341inL9a2HynGF2'

client = uservoice.Client(SUBDOMAIN_NAME, API_KEY, API_SECRET)
with client.login_as_owner() as owner:
    user = owner.get("/api/v1/users/current")
    print user
1
2
3
4
5
6
7
8
9
10
11
require 'uservoice-ruby'

SUBDOMAIN_NAME = 'uservoice'
API_KEY = 'oQt2BaunWNuainc8BvZpAm'
API_SECRET = '3yQMSoXBpAwuK3nYHR0wpY6opE341inL9a2HynGF2'

client = UserVoice::Client.new(SUBDOMAIN_NAME, API_KEY, API_SECRET)
client.login_as_owner do |owner|
  user = owner.get("/api/v1/users/current")['user']
  puts user
end

Rate Limiting

API requests have per minute rate limiting. Each request counts toward your limit. In addition, in order to account for expensive endpoints that tax our servers more, if the request takes longer than 1 second to compute then another “request” is counted for every whole second after the first.

If you are above your limit your requests will return a 429 HTTP error response.

Every request returns the following HTTP headers:

  • X-Rate-Limit-Limit: The amount of requests available every minute
  • X-Rate-Limit-Remaining: The amount of requests remaining this period
  • X-Rate-Limit-Reset: The unix epoch in seconds when the limit resets

The limit depends on your plan. See Terms of Service for details.