Not included in your plan? Want to learn more about the benefits? Leave us a message! If you're viewing this on our Help Center, click the Support bubble in the lower-right of this page.
Configure the Client
To connect to the UserVoice API, start by creating a trusted API client. Do this in your UserVoice Admin Console by navigating to Settings → Integrations → UserVoice API keys. Click the button that says “Add API Key…” and enter a name for for the client. Use a name that will help you keep track of where the token will be used (e.g Zapier Integration, or Nightly Export to BI). Leave the “APPLICATION URL” and “CALLBACK URL” text fields blank, and make sure the “Trusted” checkbox is checked. Then click the button labelled “Add API key” to create the client.
Best Practices: You can create multiple clients for specific purposes through this user interface. It’s a good idea to use a separate key for each kind of interaction that you want to build with the API. By doing so, you safely revoke keys as your needs evolve.
Warning: Never store trusted client credentials in an insecure environment (for example: in your client-side JavaScript or a public source code repository). Trusted clients have full access to perform the same actions that admins do, including deleting content.
Remember: The UserVoice API requires all calls to be made over HTTPs.
Getting the Token
To make an API call, you’ll next need to generate a token. There are two ways to do this, either through the user interface or by using the API itself.
To generate and display the token in the user interface, find your client by name in the list and click the “Create” link.
A dialog will appear with your token.
You can alternatively request a token for your UserVoice account owner with the API key and secret. Here’s how it would be done with curl:
1 2 |
|
Example response:
1
|
|
For clients where the API secret and not be safely secured, please see OAuth Authorization Code Flow with PKCE.
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.
Permissions Endpoint
Create the endpoint: POST /api/v2/admin/permissions
To add permissions to users, this requires two parameters to pass: email and license_type
The following strings are valid for license_type: "fullaccess_admin"
,"admin"
,"contributor"
, or"feedback_admin"
JSON example:
1 2 |
POST /api/v2/admin/permissions |
Updating Existing Permissions
First, you will need to find the permission record ID. To do this, use the List Permissions endpoint to find the record by the User ID.
Request: GET /api/v2/admin/permissions?user={id}
The permission record ID will appear in the response in the id
attribute.
"permissions": [
{
"id": 123456,
"license_type": "admin",
"feedback": "manage",
"features": "manage",
"settings": "manage_account",
"links": {
"user": 123456789
}
}
]
You can now use this ID with the Update Permissions endpoint.
Request: PUT /api/v2/admin/permissions/123456 { "license_type": "contributor" }
Other Permission Parameters
features |
features (string) Nullable
Default:
"none" "none" , "view" , "manage" |
feedback |
feedback (string) Nullable
Default:
"contribute" "none" , "view" ,"contribute" , "manage" |
knowledgebase |
knowledgebase (string) Nullable
Default:
"none" "none" , "view" , "manage" |
reply_to |
reply_to (string) Nullable
|
settings |
settings (string) Nullable
Default:
"none" "none" , "manage" , "manage_account" |