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 Drill-Down

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

This report is similar to the Company Report, but instead of returning statistics about the company, it drills down and returns the conversation data that makes up the Company Report.

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
page Int No The page number 1
rows Int No Number of results to return per page; defaults to 25; maximum is 50 50
range String Yes Range Details responseTime
rangeId Int Depends on range Range ID Details 1

Range

Valid values for the range parameter are listed below:

Range Value Description
replies Filters conversations by the number of replies
firstReplyResolved Selects conversations that were resolved with exactly one reply
resolved Selects conversations with at least one user reply and a status of Closed; a conversation can only be resolved once
responseTime Filters conversations by the amount of time a customers waited for a response from your team
firstResponseTime Filters conversations by the amount of time a customer waited for the first reponse from your team
handleTime Filters conversations by their average handle time (the amount of time from when a user pressed the Reply button until pressing the Send button; if a draft is saved and revisited several times, only the final visit before sending is captured as the handle time)

Range ID

Valid values for the rangeId parameters for each range value are listed below:

Range Value Range ID Meaning
replies 1 1 reply
  2 2 replies
  3 3 replies
  4 4 replies
  5 ≥ 5 replies
  (empty) All replies
firstReplyResolved (empty) N/A
resolved (empty) N/A
responseTime 1 < 15 min.
  2 15-30 min.
  3 30-60 min.
  4 1-2 hours
  5 2-3 hours
  6 3-6 hours
  7 6-12 hours
  8 12-24 hours
  9 1-2 days
  10 > 2 days
firstResponseTime 1 < 15 min.
  2 15-30 min.
  3 30-60 min.
  4 1-2 hours
  5 2-3 hours
  6 3-6 hours
  7 6-12 hours
  8 12-24 hours
  9 1-2 days
  10 > 2 days
handleTime 1 < 1 min.
  2 1-2 min.
  3 2-5 min.
  4 5-10 min.
  5 > 10 min.

Examples

To find conversations with five or more replies for the month of January, send a request with these query parameters:

start=2015-01-01T00:00:00Z&end=2015-01-31T23:59:59Z&range=replies&rangeid=5

To find conversations that were resolved on the first reply for the month of January, send a request with these query parameters:

start=2015-01-01T00:00:00Z&end=2015-01-31T23:59:59Z&range=firstReplyResolved

Response

Each response contains one object called conversations.

Response Name Type Notes
Header Status Int 200
Body conversations.pages Int The number of total available pages
  conversations.page Int The current page
  conversations.count Int The number of total conversations included in all pages
  conversations.results Collection of Abbreviated Conversations Contains abbreviated versions of each conversation associated with the search criteria

Example Response

{
  "conversations": {
    "pages": 157,
    "page": 1,
    "count": 1561,
    "results": [
      {
        "id": 583,
        "number": 12345,
        "type": "email",
        "mailboxid": 2,
        "attachments": false,
        "subject": "Sample subject",
        "status": "active",
        "threadCount": 6,
        "preview": "This is a preview...",
        "customerName": "John Smith",
        "customerEmail": "john@example.com",
        "customerIds": [
          2
        ],
        "modifiedAt": "2015-04-24T18:59:49Z",
        "assignedid": 4,
        "tags": [
          {
            "id": 123,
            "name": "sample-tag",
            "color": "none"
          }
        ],
        "assignedName": "Mary Jones"
      },
      ...
    ]
  }
}