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 Ratings

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

The user ratings report provides a user's ratings for over a specified time range.

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
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
folders list of folder identifiers No   1,2,3
user Int Yes user identifier for this report 1
page Int No The page number 1
rating Int Yes Which set of ratings to display; valid values are:
  • 0 (for all ratings)
  • 1 (for Great ratings)
  • 2 (for Okay ratings)
  • 3 (for Not Good ratings)
sortField String No Field which to sort results by; valid values are:
  • number
  • modifiedAt
  • rating
sortOrder String No Valid values are:
  • ASC
  • DESC


Response Name Type Notes
Header Status Int 200
Body pages Int The total number of pages
  page Int The current page
  count Int Total number of ratings
  results Collection Collection of details about each rating for a given user for a given time range
  results[index].number Int The conversation number
  results[index].id Int The unique conversation identifier
  results[index].type String The type of conversation; valid values include:
  • email
  • chat
  • phone
  results[index].threadid Int Unique identifier for the thread associated with this rating
  results[index].threadCreatedAt Date/Time ISO 8601, in UTC
  results[index].ratingId Int Unique identifier of the rating
  results[index].ratingCustomerId Int Unique identifier of the customer who submitted this rating
  results[index].ratingComments String Comments the customer submitted (if any)
  results[index].ratingCreatedAt Date/Time ISO 8601, in UTC
  results[index].ratingCustomerName String Name of the customer who submitted this rating
  results[index].ratingUserId Int Unique identifier of the user associated with this rating
  results[index].ratingUserName String Name of the user associated with this rating

Example Response

  "pages": 1,
  "page": 1,
  "count": 10,
  "results": [
      "number": 59504,
      "id": 1545009,
      "type": "email",
      "threadid": 2952132,
      "threadCreatedAt": "2015-01-14T15:09:39Z",
      "ratingId": 1,
      "ratingCustomerId": 449122,
      "ratingComments": "",
      "ratingCreatedAt": "2015-01-14T15:10:40Z",
      "ratingCustomerName": "john@example.com",
      "ratingUserId": 4,
      "ratingUserName": "John Smith"