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.

Docs Report

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

The Docs report provides statistics about Docs usage (searches, top articles, etc.) over a given time range. You may optionally specify two time ranges to see how usage changed between the two ranges.

URL Parameters

A variety of filters are available as query parameters. Including any of these will result in only results 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
sites list of site identifiers No 1,2,3

Response

Response Name Type Notes
Header Status Int 200
Body current Object Statistics about Docs usage for the current time range; each object contains:
  • failedResult: Percentage of views where the customer exited without viewing an article
  • docsViewedPerVisit: Average number of articles viewed by a customer during a session on the website; sessions expire after 30 minutes of inactivity
  • foundAnAnswerResult: Percentage of views where the customer viewed an article and didn't contact support
  • visitors: Visits from unique browsers
  • browseAction: Percentage of views due to browsing
  • searchAction: Percentage of views due to searching
  • sentAnEmailResult: Percentage of views where the customer then sent an email to support
  previous Object Statistics about Docs usage for the previous time range; only included if a previous time range was specified; each object contains:
  • failedResult: Percentage of views where the customer exited without viewing an article
  • docsViewedPerVisit: Average number of articles viewed by a customer during a session on the website; sessions expire after 30 minutes of inactivity
  • foundAnAnswerResult: Percentage of views where the customer viewed an article and didn't contact support
  • visitors: Visits from unique browsers
  • browseAction: Percentage of views due to browsing
  • searchAction: Percentage of views due to searching
  • sentAnEmailResult: Percentage of views where the customer then sent an email to support
  popularSearches Collection Collection of objects containing statistics about popular searches; each element contains:
  • deltaPercent: Percentage change in search popularity for this search term
  • id: The actual search term
  • results: How many results were returned
  • count: Number of times the search term was used for the current time range
  • previousCount: Number of times the search term was used for the previous time range
  failedSearches Collection Collection of objects containing statistics about failed searches; each element contains:
  • deltaPercent: Percentage change in search popularity for this search term
  • id: The actual search term
  • count: Number of times the search term was used for the current time range
  • previousCount: Number of times the search term was used for the previous time range
  topArticles Collection Collection of objects containing statistics about top articles; each element contains:
  • deltaPercent: Percentage change in popularity of this article
  • id: The article identifier
  • siteId: The site identifier
  • count: Number of times this article was viewed for the current time range
  • collectionId: The collection identifier
  • name: Name of the article
  • previousCount: Number of times the article was viewed for the previous time range
  topCategories Collection Collection of objects containing statistics about top article categories; each element contains:
  • deltaPercent: Percentage change in popularity of this category
  • id: The category identifier
  • articles: Number of articles in this category
  • siteId: The site identifier
  • count: Number of times articles in this category were viewed for the current time range
  • name: Name of the category
  • previousCount: Number of times articles in this category were viewed for the previous time range
  deltas Object Statistics showing how Docs usage changed between two time ranges; only included if a previous time range was specified; each object contains:
  • failedResult: Percentage change visits where the customer exited without viewing an article
  • docsViewedPerVisit: Percentage change customers who exited without viewing an article
  • foundAnAnswerResult: Percentage change in customers who viewed an article and didn't contact support
  • visitors: Percentage change in visits from unique browsers
  • browseAction: Percentage change in views due to browsing
  • searchAction: Percentage change in views due to searching
  • sentAnEmailResult: Percentage change in views where the customer then sent an email to support

Example Response

{
  "current": {
    "failedResult": 25.27642465011985,
    "docsViewedPerVisit": 1.2078855817549286,
    "foundAnAnswerResult": 73.6410732235367,
    "visitors": 12933,
    "browseAction": 87.39218205175263,
    "searchAction": 12.607817948247385,
    "sentAnEmailResult": 1.0825021263434627
  },
  "previous": {
    "failedResult": 22.87430683918669,
    "docsViewedPerVisit": 1.177713229469237,
    "foundAnAnswerResult": 76.34671243728545,
    "visitors": 15148,
    "browseAction": 89.54703832752612,
    "searchAction": 10.452961672473867,
    "sentAnEmailResult": 0.7789807235278585
  },
  "popularSearches": [
    {
      "deltaPercent": 30.434782608695656,
      "id": "api",
      "results": 32,
      "count": 90,
      "previousCount": 69
    },
    ...
  ],
  "failedSearches": [
    {
      "deltaPercent": 192.85714285714286,
      "id": "ldap",
      "count": 41,
      "previousCount": 14
    },
    ...
  ],
  "topArticles": [
    {
      "deltaPercent": -9.49685534591195,
      "id": "...",
      "siteId": "...",
      "count": 1439,
      "collectionId": "...",
      "name": "Custom SMTP settings for Gmail",
      "previousCount": 1590
    },
    ...
  ],
  "topCategories": [
    {
      "deltaPercent": -6.845324788814448,
      "id": "...",
      "articles": 13,
      "siteId": "...",
      "count": 3198,
      "name": "Productivity",
      "previousCount": 3433
    },
    ...
  ],
  "deltas": {
    "failedResult": 2.4021178109331593,
    "docsViewedPerVisit": 2.561943903720043,
    "foundAnAnswerResult": -2.7056392137487535,
    "visitors": -14.622392395035643,
    "browseAction": -2.154856275773497,
    "searchAction": 2.1548562757735183,
    "sentAnEmailResult": 0.30352140281560414
  }
}
↑Back to top
© Help Scout 2024