Company Drilldown

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.

Note: The reporting endpoints are only available to Plus and Pro plans.

Request

GET /v2/reports/company/drilldown HTTP/1.1
Authorization: Bearer oauth_token

URL Parameters

Parameter Type Examples Description
start date start=2019-05-02T12:00:00Z
 Start of the interval
end date end=2019-06-02T12:00:00Z
 End of the interval
mailboxes number mailboxes=123
mailboxes=123,567
 List of comma separated ids to filter on mailboxes
tags number tags=99787
tags=5666,99787
 List of comma separated ids to filter on tags
types enumeration types=email
 List of comma separated conversation types to filter on, valid values are email, chat, phone
folders number folders=991
folders=991,992
 List of comma separated folder ids to filter on folders
page number page=2
 The page number
rows number rows=30
 Number of result to return per page; defaults to 25; maximum is 50
range enumeration range=replies
 Range details: see Valid ranges
rangeId number rangeId=2
 Range ID details, only valid if range is used: see Valid range IDs

Valid Ranges

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 opens a conversation 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)

Valid Range IDs

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

HTTP/1.1 200 OK
Content-Type: application/json

{
  "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"
    } ]
  }
}

Response fields

Path Type Description
conversations.pages Number The number of total available pages
conversations.page Number The current page
conversations.count Number The number of total conversations included in all pages
conversations.results Array Contains abbreviated versions of each conversation associated with the search criteria

Response fields

Path Type Description
id Number Unique identifier of the conversation
number Number The conversation number displayed in the UI. This number can be used in combination with the id to construct a URL to the conversation on the Help Scout website. Example: https://secure.helpscout.net/conversation/<id>/<number>/
type String The type of conversation; Accepted values are:
chat
email
phone
mailboxid Number Identifier of the mailbox in which this conversation resides
attachments Boolean attachments
subject String Conversation subject
status String Status of the conversation; Accepted values are:
active
closed
open
pending
spam
threadCount Number The number of published threads found on the conversation (does not include line items, drafts or threads held for review by Collision Detection)
preview String Preview of the most recent thread in the conversation
customerName String The customer who this conversation is associated with
customerEmail String The customer email address who this conversation is associated with
customerIds Array Identifiers of customer this conversation is associated with
modifiedAt String The date/time this conversation was last modified
assignedid Number The identifier of the user assigned to this conversation
assignedName String The name of the User assigned to this conversation
tags Array Collection of tags with each element containing the tag identifier, name, and color
↑Back to top
© Help Scout 2024