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.

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