mozilla

Feedback API

The Feedback API is for getting/posting product feedback data.

Getting product feedback: GET /api/v1/feedback/

URL:/api/v1/feedback/
Method:HTTP GET
Payload format:No payload–everything is done in the querystring
Response:JSON

Doing a GET without any querystring arguments will return the most recent 1,000 publicly visible responses for all products.

Warning

This API endpoint is throttled. If you hit it too often, you’ll get throttled. You just need to wait a bit for the throttle to expire.

Note

This API endpoint is still in flux. The documentation is rudimentary at best. Amongst other things, it’s difficult to discover valid values for things.

If you’re using this API endpoint and have issues, please open a bug.

Filters

id

String. Comma-separated list of feedback response ids.

Example:

?id=1
?id=1,2,3,4

Note

If you specify this, all other filters will be ignored.

q

String. Text query.

Example:

?q=crash
happy

Boolean. 0 or 1. Restricts results to either happy feedback or sad feedback.

Example:

?happy=0
platforms

Strings. Comma separated list of platforms. For valid platforms, see https://input.mozilla.org/.

Examples:

?platforms=linux
?platforms=linux,os x
locales

Strings. Comma separated list of locales. For valid locales, see https://input.mozilla.org/.

Examples:

?locales=en-US
?locales=en-US,es,es-BR
products

Strings. Comma separated list of products. For valid products, see https://input.mozilla.org/.

Examples:

?products=Firefox
?products=Firefox OS,Firefox
versions

Strings. Comma separated list of versions for a specific product. For valid versions, see https://input.mozilla.org/.

You must specify a product in order to specify versions.

Examples:

?products=Firefox&versions=31.0
?products=Firefox&versions=31.0,32.0
date_start

Date in YYYY-MM-DD format. Specifies the start for the date range you’re querying for.

Example:

?date_start=2014-08-12
date_end

Date in YYYY-MM-DD format. Specifies the end for the date range you’re querying for.

Defaults to today.

Example:

?date_end=2014-08-12
date_delta

String. 1d, 7d, 14d, etc. The number of days from date_start or date_end.

Example:

# Shows the last 7 days ending today
?date_delta=7d

# Shows 14 days ending 2014-08-12
?date_end=2014-08-12&date_delta=14d

# Shows 22 days starting 2014-08-12
?date_start=2014-08-12&date_delta=22d

max

Integer. Defaults to 1,000. Maximum is 10,000. Minimum is 1. The maximum number of responses you want to get back.

Example:

# Retrieve at most 500 responses
?max=500

# Retrieve at most 10000 responses
?max=10000

Examples

Show all the happy responses for Firefox for the last 7 days for the English locale:

?happy=1&products=Firefox&locales=en-US&date_delta=7d

Show sad responses for Windows platforms for the last day:

?happy=0&platforms=Windows 7,Windows XP, Windows 8.1,Windows 8,Windows Vista,Windows NT&date_delta=1d

Posting product feedback: POST /api/v1/feedback/

URL:/api/v1/feedback/
Method:HTTP POST
Payload format:JSON—make sure to have Content-type: application/json header

Testing clients using the API

You can test early stages of your code against our -stage server at:

https://input.allizom.org/

But you want to make sure you test against production at some point since that’s where the product you’re using will be set up. Production is:

https://input.mozilla.org/
              ^^^^^^^

Note

If you’re building automated testing, you can use our -prod server, but include the word TEST at the beginning of the description.

Required fields

happy

Boolean. All feedback is either happy or sad. This denotes whether this feedback is happy (True) or sad (False).

Valid values: true, false

description

String. Max length: None (but 10,000 characters is probably a good cutoff). This is the feedback text.

Example: "OMG! I love Firefox!"

Note

The form this field is on should have some informational text stating that data in this field will be publicly available and that the user should not include personally identifyable information.

Example informational text:

The content of your feedback will be public, so please be sure
not to include any personal information.
product

String. Max length: 20. The name of the product the user is giving feedback on.

Examples:"Firefox for Android", "Firefox OS"

Note

This must be a valid product in the system. Before you start posting to Input, please talk to the User Advocacy folks or an Input admin to have your product added.

Optional fields

channel

String. Max length: 30. The channel of the product the user is giving feedback on.

Examples: "stable", "beta"

version

String. Max length: 30. The version of the product the user is giving feedback on as a string.

Examples: "22b2", "1.1"

platform

String. Max length: 30. The name of the operating system/platform the product is running on.

Examples: "OS X", "Windows 8", "Firefox OS", "Android", "Linux"

locale

String. Max length: 8. The locale the user is using.

Examples: "en-US", "fr", "de"

country

String. Max length: 30. The country of origin for the device.

Examples: "Peru", "Mexico"

Note

This is only relevant to Firefox OS phones.

manufacturer

String. Max length: 255. The manufacturer of the device the product is running on.

Examples: "Geeksphone", "Samsung"

device

String. Max length: 255. The model name of the device the product is running on.

Examples: "Peak", "Galaxy Tab 10.1"

category

String. Max length: 50. The category classification for this feedback response.

Examples: "ui", "performance", "bookmarks"

url

String. Max length: 200. If the feedback relates to a specific webpage, then the url is the url of the webpage it refers to.

Examples: "https://facebook.com/", "https://google.com/"

email

String. The email address of the user. This allows us to contact the user at some later point to respond to the user’s feedback or ask for more information.

Example: "joe@example.com"

Note

The form this field is in should state that email addresses will not be publicly available.

Example informational text:

While your feedback will be publicly visible, email addresses
are kept private. We understand your privacy is important.
user_agent

String. Max length: 255. The user agent of the client if applicable. For example if the user is using a Firefox OS device, this would be the user agent of the browser used to send feedback.

Example: 'Mozilla/5.0 (Mobile; rv:18.0) Gecko/18.0 Firefox/18.0'

source

String. Max length: 100. If this response was initiated by a blog post, wiki page, search, newsletter, tweet or something like that, this is the source that initiated the response. It has the same semantics as the utm_source querystring parameter:

https://support.google.com/analytics/answer/1033867

Example: 'Hacks blog'

Note

Don’t set the source if the user is leaving feedback of their own accord. Only set the source if you have prompted or asked the user to leave feedback.

campaign

String. Max length: 100. If this response was initiated by a marketing campaign, this is the name of the campaign. It has the same semantics as the utm_campaign querystring parameter:

https://support.google.com/analytics/answer/1033867

Example: 'show the firefox love post'

Note

Don’t set the campaign if the user is leaving feedback of their own accord. Only set the campaign if you have prompted or asked the user to leave feedback.

Extra context

You can provide additional context in the form of key/value pairs by adding additional data to the JSON object.

Any fields that aren’t part of the required or optional fields list will get thrown into a JSON object and dumped in the feedback response context.

For example, if the product were the Firefox devtools and you want feedback responses to include the theme (dark or light) that the user was using, you could add this to the JSON object:

{
    "happy": true,
    "description": "devtools are the best!",
    "product": "Devtools",
    "theme": "dark"
}

That last key will get added to the feedback response context.

Note

Obviously, don’t use a key that’s already the name of a field. Also, since this is not future proof, you might want to prepend a unique string to any keys you add.

Note

It’s important you don’t add ids or data that allows you to correlate feedback responses to things in other data sets. That violates our privacy policy.

Minimal example with curl

$ curl -v -XPOST 'https://input.allizom.org/api/v1/feedback' \
    -H 'Accept: application/json; indent=4' \
    -H 'Content-type: application/json' \
    -d '
{
    "happy": true,
    "description": "Posting by api!",
    "product": "Firefox"
}'

Responses

After posting feedback, you’ll get one of several responses:

HTTP 201
Feedback was posted successfully.
HTTP 400

Feedback has errors. Details will be in the response body.

Possibilities include:

  • missing required fields
  • email address is malformed
  • data is in the wrong format
HTTP 429
There has been too many feedback postings from this IP address and the throttle trigger was hit. Try again later.