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.
Company Report
- REST Method: GET
- URLs: https://api.helpscout.net/v1/reports/company.json
The company report provides statistics about your company performance over a given time range. You may optionally specify two time ranges to see how performance 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 | Example |
|---|---|---|---|
| start | Date/Time (ISO 8601, in UTC) | Yes | 2015-01-01T00:00:00Z |
| end | Date/Time (ISO 8601, in UTC) | Yes | 2015-01-31T23:59:59Z |
| previousStart | Date/Time (ISO 8601, in UTC) | No | 2014-01-01T00:00:00Z |
| previousEnd | Date/Time (ISO 8601, in UTC) | No | 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 (email, chat, or phone) | No | email,chat |
| folders | list of folder identifiers | No | 1,2,3 |
Response
| Response | Name | Type | Notes |
|---|---|---|---|
| Header | Status | Int | 200 |
| Body | filterTags | Collection | All tags available for filtering in reports, including tag id=1, which represents conversations that are untagged |
| current | Time Range Statistics (Company) | Statistics about company performance for the current time range | |
| previous | Time Range Statistics (Company) | Statistics about company performance for the previous time range; only included if a previous time range was specified | |
| deltas | Multiple Time Range Statistics (Company) | Statistics showing how company performance changed between two time ranges; only included if a previous time range was specified | |
| users | Collection of User Statistics (Company) | Statistics about each user's performance |
Example Response
{
"filterTags": [
{
"id": 123,
"name": "sample-tag"
},
...
],
"current": {
"startDate": "2015-01-01T00:00:00Z",
"endDate": "2015-01-31T23:59:59Z",
"customersHelped": 28,
"closed": 94,
"totalReplies": 62,
"totalUsers": 5,
"totalDays": 30,
"repliesPerDayPerUser": 0.41333333333333333,
"repliesPerDay": 2.066666666666667,
"resolvedPerDay": 0.03333333333333333
},
"previous": {
"startDate": "2014-01-01T00:00:00Z",
"endDate": "2014-01-31T23:59:59Z",
"customersHelped": 27,
"closed": 49,
"totalReplies": 636,
"totalUsers": 4,
"totalDays": 30,
"repliesPerDayPerUser": 5.3,
"repliesPerDay": 21.2,
"resolvedPerDay": 0.4666666666666667
},
"deltas": {
"customersHelped": 3.703703703703698,
"totalReplies": -90.25157232704403,
"repliesPerDay": -90.25157232704403,
"closed": 91.83673469387755,
"totalUsers": 25.0,
"repliesPerDayPerUser": -92.20125786163523
},
"users": [
{
"customersHelped": 26,
"happinessScore": 66.66666666666666,
"previousCustomersHelped": 16,
"replies": 58,
"name": "John Smith",
"previousHappinessScore": 23.529411764705884,
"previousReplies": 40,
"user": "1",
"previousHandleTime": 0.0,
"handleTime": 78.96
},
...
]
}