Getting Started with the Idea Collection API

~ minute read
This is available in UserVoice Discovery.

The Idea Collection API can be used to develop custom experiences for capturing feedback from your users via a number of different platforms, including mobile. You can find an example iOS app here on GitHub.

Configure the Client

UserVoice follows the OAuth2 specification for authenticating access to its APIs. For public clients, such as a Native App, it is highly recommended to authenticate using the Authorization Code Grant flow with PKCE.

To configure your application to use the UserVoice Idea Collection API please follow the steps below:

  1. From Admin Settings > Integrations, create a new API Key to be used by your app:

    Add API Key

  2. Give your API Key a name and specify your Redirect URI (where your client Auth resides) as the Callback URL:

    Configure API Key

    NOTE: Read more about Redirect URIs for Native Apps in OAuth 2.0 for Native Apps (Page 8). NOTE: It is not necessary to select the “Trusted?” option for clients using the /end_users/ API. If you do, do not expose your key.

  3. From your application, request an Authorization Code using the API key created above:
    https://<YOUR_SUBDOMAIN>.uservoice.com/api/v2/oauth/auth?client_id=<YOUR_API_KEY>&redirect_uri=<YOUR_REDIRECT_URI>&response_type=code&code_verifier=<YOUR_ENCODED_VERIFIER>&code_challenge_method=S256

    NOTE: The code_verifier and code_challenge_method params are optional. UserVoice only currently supports S256 as the code_challenge_method. Learn more about PKCE.

  4. The GET request above returns a redirect to a UserVoice Sign In page. Once the user successfully authenticates, they will be directed back to the Redirect URI with a query parameter containing the authorization code:

    Sign-in

    Example Redirect:
    https://<YOUR_REDIRECT_URI>?code=<UV_AUTH_CODE>

  5. With the acquired Authorization Code, submit a POST request to obtain a bearer token:
    http://<YOUR_SUBDOMAIN>.uservoice.com/api/v2/oauth/token?grant_type=authorization_code&client_id=<YOUR_API_KEY>&code=<YOUR_DECODED_VERIFIER>

    Example Response:
    { "access_token": "<YOUR_TOKEN>" }

  6. Include this token in the Authorization header of every API request:

    Authorization: Bearer <YOUR_TOKEN>

 

Rate Limiting

API requests have per-minute rate limiting. Each request counts toward your limit. Not all requests are created equal: if a request takes longer than 1 second to compute then another “request” is counted for every whole second after the first. This helps us account for expensive endpoints (like complex searches) that use more resources.

Once you have exceeded your limit for the current minute, the UserVoice Idea Collection API will return a 429 HTTP error response for subsequent requests.

Every request returns the following HTTP headers:

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

Once rate limited, every request returns the following HTTP header:

  • Retry-After: The unix epoch in seconds until the rate limit expires

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

Take advantage of side-loading, per_page settings and bulk endpoints to consolidate your requests.

Related articles