Technical details of Helpdesk API

The 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.

What is an API client

The API client is created in UserVoice Admin Console → Settings → Channels, scroll down, and click Add API Client.

If you’ve ever used an API before you can think of the client as your API KEY. It’s required to help identify your application whether that be a web application, a server-side script that does some backend integration or a piece of Javascript that pulls down the ideas on your forum.

A quick overview of the fields:

• Name- It’s there to help you remember what this API Key was intended for.
• Trusted?- A number of 2-legged OAuth endpoints require a trusted client to work. Do NOT check this if your API Key will be stored in an insecure environment (ex: Javascript or compiled application that end-users download)!
• Application URL(optional) - URL of your web application that’s using the Helpdesk API.This is only relevant if your client is a web application that will require users to authorize its access to their UserVoice data.
• Callback URL(optional) - URL in your web application where users should be returned to after they authorize access to their UserVoice data.This is only relevant if your client is a web application that will require users to authorize its access to their UserVoice data.

Various types of API requests

Helpdesk API requests can be divided in three categories:

• Unauthenticated Requests- Requests you can make without any authentication other than passing your API Key. ex: Retrieving ideas or comments from a public forum.
• 3-legged OAuth requests- Requests made on the behalf of a user (see any API endpoints marked as requiring a User or Admin). ex: Voting on an idea, Creating a comment, Responding to a idea..
• 2-legged OAuth requests- Requests made on behalf of the client not on behalf of any specific user (see any API endpoints marked as requiring a Trusted Client) ex: Retrieving all users for a site, Getting a list of ideas for a private forum.

The first scenario is pretty straightforward the other two require the use of OAuth and can be a bit tricky if you’ve never used OAuth before.

Option A : Unauthenticated requests

Making an unauthenticated request is very simple. You simply need to pass your KEY to the API via the client parameter. For example:

e.g GET http://youraccount.uservoice.com/api/v1/forums/1/suggestions.json?client=XXXXX

Option B : 3-Legged OAuth requests

In this scenario all actions take place on behalf of a user.

• The 3-legged OAuth requests mean the standard web authentication system (OAuth 1.0a) in which you redirect an existing user to UserVoice for them to authorize a token that grants your application access to perform actions on their behalf in UserVoice. This is particularly suitable to building integrations between UserVoice and other web applications.

For this you’ll follow the standard OAuth dance:

• Retrieve a Request Token
• Redirect the user to UserVoice to authorize your application
• The user is redirected to the Callback URL you defined in your Client
• Exchange the Request Token for an Access Token
• Make requests using the AccessToken

Going into details about specific parameters, request signing and the other intricacies of OAuth are outside the scope of this document. Luckily OAuth is a standard not something we just made up so there are a number of resources and libraries out there that will do a lot of heavy lifting for you. Here’s a good starting point:

• Linked In OAuth Zero to Hero
• Heuniverse Beginners Guide to OAuth

Option C : 2-Legged OAuth requests

In this scenario there is no user involved in the OAuth dance. You simply create an access token from your consumer and then make requests against the API. This is particularly suitable for creating scripts and performing routine backup and administration. You can not act on behalf of a user using 2-Legged OAuth and many of the endpoints will require that your client be trusted (see ‘Creating an API client’).

Parting Thoughts

A few things to keep in mind as you embark on your journey:

• Private forums, or any content in a private forum, will not be returned unless you’re logged in with a user that has access to view that forum.
• User emails will only be returned if you’re authenticating with admin privileges.
• You can only UPDATE an item if you’re the user that created it.
• SHOW endpoints will return more data than LIST.
• OAuth libraries will by default connect to to the standard OAuth endpoints located at http://uservoice.uservoice.com/oauth/* which are slightly different than the OAuth endpoints at http://uservoice.uservoice.com/api/v1/oauth/*. The /oauth/* endpoints support cross-subdomain OAuth, which is sometimes useful.