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/Team Report

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

Please note that if a team ID is used instead of an user ID, the report calculates summary data for all team members

The report provides a snapshot of a user or team activity over a specified time range. You may optionally specify two time ranges to see how activity changed between the two 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
officeHours Boolean (0/1) No Whether to take office hours into consideration in the report (defaults to 0); office hours must be enabled if 1 is passed, otherwise the default of 0 will be used 1
user user or team identifier for this report Yes   1

Response

Response Name Type Notes
Header Status Int 200
  filterTags Collection All tags available for filtering in reports
  user Object Basic information about the user
  current Time Range Statistics (User) Statistics about the user for the current time range
  previous Time Range Statistics (User) Statistics about the user for the previous time range; only included if a previous time range was specified
  deltas Multiple Time Range Statistics (User) Statistics showing how the user's metrics changed between two time ranges; only included if a previous time range was specified

Example Response

{
  "filterTags": [
    {
      "id": 123,
      "name": "sample-tag"
    },
    ...
  ],
  "user": {
    "id": 4,
    "hasPhoto": true,
    "createdAt": "2010-09-03T15:55:48Z",
    "name": "John Smith",
    "totalCustomersHelped": 6580,
    "photoUrl": "http://example.com/pic.jpg"
  },
  "current": {
    "startDate": "2015-01-01T00:00:00Z",
    "endDate": "2015-01-31T23:59:59Z",
    "totalDays": 30,
    "resolved": 1,
    "conversationsCreated": 15,
    "closed": 3,
    "totalReplies": 58,
    "resolvedOnFirstReply": 0,
    "percentResolvedOnFirstReply": 0.0,
    "repliesToResolve": 2.0,
    "handleTime": 78.96,
    "happinessScore": 66.66666666666666,
    "responseTime": 2278004,
    "resolutionTime": 2278004.0,
    "repliesPerDay": 1.9333333333333333,
    "customersHelped": 26,
    "totalConversations": 19,
    "conversationsPerDay": 0.6333333333333333,
    "busiestDay": 5
  },
  "previous": {
    "startDate": "2014-01-01T00:00:00Z",
    "endDate": "2014-01-31T23:59:59Z",
    "totalDays": 30,
    "resolved": 12,
    "conversationsCreated": 2,
    "closed": 33,
    "totalReplies": 40,
    "resolvedOnFirstReply": 4,
    "percentResolvedOnFirstReply": 0.3333333333333333,
    "repliesToResolve": 2.1666666666666665,
    "handleTime": 0.0,
    "happinessScore": 23.529411764705884,
    "responseTime": 2357169,
    "resolutionTime": 4318101.5,
    "repliesPerDay": 1.3333333333333333,
    "customersHelped": 16,
    "totalConversations": 42,
    "conversationsPerDay": 0.4
  },
  "deltas": {
    "totalConversations": -54.761904761904766,
    "customersHelped": 62.5,
    "happinessScore": 43.13725490196077,
    "repliesPerDay": 45.000000000000014,
    "resolvedOnFirstReply": -100.0,
    "handleTime": 0.0,
    "conversationsPerDay": 58.33333333333333,
    "resolved": -91.66666666666666,
    "repliesToResolve": -7.692307692307687,
    "activeConversations": -54.761904761904766,
    "totalReplies": 44.99999999999999,
    "closed": -90.9090909090909,
    "responseTime": -3.3584779029420475,
    "resolutionTime": -47.245241919394445,
    "conversationsCreated": 650.0
  }
}