Legacy Mailbox API 1.0 is deprecated

Legacy Mailbox API 1.0 was deprecated on November 20, 2019. Please use Mailbox API 2.0 going forward. If you have any questions or need help with the new API, please reach out.

User Happiness

  • REST Method: GET
  • URLs: https://api.helpscout.net/v1/reports/user/happiness.json

The happiness report provides information about how many Great, Okay, and Not Good ratings a user received for each period in a specified time range. You may optionally specify two time ranges to see how happiness ratings changed between the two time ranges.

URL Parameters

A variety of filters are available as query parameters. Including any of these will result in only conversations that match the filters being included in the report.

Parameter Type Required Notes Example
start Date/Time Yes ISO 8601, in UTC 2015-01-01T00:00:00Z
end Date/Time Yes ISO 8601, in UTC 2015-01-31T23:59:59Z
previousStart Date/Time No ISO 8601, in UTC 2014-01-01T00:00:00Z
previousEnd Date/Time No ISO 8601, in UTC 2014-01-31T23:59:59Z
mailboxes list of mailbox identifiers No   1,2,3
tags list of tag identifiers No   1,2,3
types list of conversation types No Valid values are:
  • email
  • chat
  • phone
email,chat
folders list of folder identifiers No   1,2,3
user user identifier for this report Yes   1

Response

Response Name Type Notes
Header Status Int 200
Body previous Time Range Statistics (Happiness) Statistics about happiness ratings received for this user for the current time range
  current Time Range Statistics (Happiness) Statistics about happiness ratings received for this user for the previous time range
  deltas Multiple Time Range Statistics (Happiness) Statistics about how happiness ratings received for this user changed between two time ranges

Example Response

{
  "filterTags": [
    {
      "id": 123,
      "name": "sample-tag"
    },
    ...
  ],
  "current": {
    "ratingsPercent": 35.77981651376147,
    "okay": 30.909090909090907,
    "great": 37.27272727272727,
    "happinessScore": 5.454545454545457,
    "okayCount": 34,
    "totalCustomersWithRatings": 39,
    "notGoodCount": 35,
    "ratingsCount": 110,
    "notGood": 31.818181818181817,
    "greatCount": 41,
    "totalCustomers": 109
  },
  "previous": {
    "ratingsPercent": 32.03047366677708,
    "great": 31.65735567970205,
    "okay": 36.49906890130354,
    "happinessScore": -0.1862197392923619,
    "okayCount": 392,
    "totalCustomersWithRatings": 967,
    "notGoodCount": 342,
    "ratingsCount": 1074,
    "notGood": 31.843575418994412,
    "greatCount": 340,
    "totalCustomers": 3019
  },
  "deltas": {
    "okay": -5.589977992212631,
    "great": 5.615371593025223,
    "okayCount": -91.3265306122449,
    "happinessScore": 5.640765193837819,
    "notGoodCount": -89.76608187134502,
    "notGood": -0.02539360081259545,
    "greatCount": -87.94117647058823
  }
}