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.

Conversations Drill-Down (by Field)

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

This report is similar to the Conversations Report, but instead of returning statistics about conversation volume, it drills down and returns the conversation data (by conversation field) that makes up the Conversations 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 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
field The field on which to drill down; valid values are:
  • tagid (for tags)
  • replyid (for saved replies)
  • workflowid (for workflows)
  • customerid (for most active customers)
 Yes tagid
fieldid The identifier on which to drill down; can be an identifier representing a tag, saved reply, workflow, or customer Yes 123
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
page The page number No 1
rows Number of results to return per page; defaults to 10; maximum is 50 No 50

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"
      },
      ...
    ]
  }
}
↑Back to top
© Help Scout 2024