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.
A quick overview of the fields:
- Name- It’s there to help you remember what this API Key was intended for.
- 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:
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:
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’).
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.