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/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 |
| 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
}
}