Please note! This version of the API is in beta and may change. If you would like to use a stable version of the API please see version 1.

Getting Started with the UserVoice API v2

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

Step 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. Make sure the “Trusted” checkbox is checked:

At this time all API v2 endpoints require a trusted client. BEWARE: You should never store trusted client credentials (API key and secret) in an insecure environment. (For example: in your client-side JavaScript that is downloaded by your end users!) Trusted clients have full access to do almost anything that an admin can do in UserVoice 3.0. This includes potential destructive actions like deleting suggestions or blocking users.

Step 2: Get an authorization token

Alright! You’re almost ready. Now, get the API key and secret from the API client you created in step one. You’ll see it in the listing of API clients under the name of the client you just created.

To make an API request, you will need an API token. You can request a token for your UserVoice account owner with the API key and secret. Here’s how it would be done with curl:

$ curl https://SUBDOMAIN.uservoice.com/api/v2/oauth/token \
       --data "grant_type=client_credentials;client_id=KEY;client_secret=SECRET"
Example response:
{"access_token": "096e8ae9c6a3c039"}

Alternatively, if you would like to take action as another user, you can request a token with just your API key (no secret is necessary) and that user’s email and password:

$ curl https://SUBDOMAIN.uservoice.com/api/v2/oauth/token \
       --data "grant_type=password;client_id=KEY;username=EMAIL;password=PASSWORD"
Example response:
{"access_token": "56c2ae9e3139070b"}

Step 3: Make an API request

Once you have a token, you can make API requests on behalf of a user. Just pass an authorization header with your token. Here’s how you would do that with curl:

$ curl https://SUBDOMAIN.uservoice.com/api/v2/admin/users/current \
       -H "Authorization: Bearer TOKEN"
Example response:
{
  "links": {},
  "users": [
    {
      "id": 14611580,
      "guid": "14611580",
      "name": "John Smith",
      "email_address": "test@example.com",
      "job_title": "",
      "avatar_url": "https://secure.gravatar.com/avatar/d0421b38238272c4ceddabb6c426b222...",
      "satisfaction_score": 8,
      "allowed_state": "allowed",
      "last_login": "2015-09-28T15:50:31Z",
      "traits": {
        "id": "14611580",
        "account_created_at": 1193712545000,
        "account_id": "44",
        "account_name": "Acme",
        "email": "test@example.com",
        "name": "John Smith",
        "account_ltv": 722.5,
        "account_monthly_rate": 0,
        "account_plan": "Enterprise",
        "browser_name": "Chrome",
        "location_city": "Redmond",
        "location_country": "United States",
        "location_region": "WA",
        "os_name": "Mac OS X",
        "type": "Admin"
      },
      "created_at": "2011-07-25T22:01:40Z",
      "updated_at": "2015-09-28T15:50:31Z"
    }
  ]
}

Bodies for POST and PUT requests can be passed as either JSON or url-form-encoded data.

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.

Want do all of this with Ruby? See this gist.

A complete list of endpoints is available in our API v2 Reference.