Getting Started with the Helpdesk API

The UserVoice Helpdesk 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 → Helpdesk 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.

1

Install-Package UserVoice

1
2
3
4
5

<dependency>
  <groupId>com.uservoice</groupId>
  <artifactId>uservoice-java</artifactId>
  <version>0.0.2</version>
</dependency>

1

mvn clean install

1
2

extension=oauth.so
extension=mcrypt.so

1
2
3
4
5

{
  "require": {
    "uservoice/uservoice": ">=0.0.6"
  }
}

1

php composer.phar install

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

1

pip install uservoice

1
2

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

1

gem 'uservoice-ruby'

1

bundle install

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.