We're upgrading our API

On June 6th, 2019, Mailbox API 1.0 will be sunsetted, and at that time any apps using this legacy API will no longer work. Please use Mailbox API 2.0 instead.

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
email,chat
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)
1
sortField String No Field which to sort results by; valid values are:
  • number
  • modifiedAt
  • rating
rating
sortOrder String No Valid values are:
  • ASC
  • DESC
ASC

Response

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"
    },
    ...
  ]
}