Skip to content

Commit c3b2c58

Browse files
zackkatzzackkatz
committed
Update documentation
1 parent aa0e4e0 commit c3b2c58

File tree

1 file changed

+148
-1
lines changed

1 file changed

+148
-1
lines changed

‎help-scout-complete-api-documentation.md‎

Lines changed: 148 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1226,43 +1226,190 @@ Help Scout provides comprehensive reporting capabilities across multiple categor
12261226

12271227
**Volume by Channel Report**
12281228
- **Endpoint**: `GET /v2/reports/conversations/volume-by-channel`
1229+
- **Required Parameters**: `start`, `end`
1230+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`
1231+
- **View Options**: `viewBy` (day ≤60 days, week ≤1 year, month ≥61 days)
1232+
- **Response**: Time-series data with channel breakdown (chat, email, phone counts)
1233+
- **Example**: `[{"date": "2018-10-01T12:00:00Z", "chat": 12, "email": 35, "phone": 6}]`
12291234

12301235
**Busiest Time of Day Report**
1231-
- **Endpoint**: `GET /v2/reports/conversations/busiest-time`
1236+
- **Endpoint**: `GET /v2/reports/conversations/busy-times`
1237+
- **Required Parameters**: `start`, `end`
1238+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`
1239+
- **Response**: Array of objects with day (1-7), hour (0-23), and conversation count
1240+
- **Time Zone**: Uses company's configured time zone
1241+
- **Example**: `[{"day": 1, "hour": 9, "count": 25}, {"day": 7, "hour": 22, "count": 12}]`
12321242

12331243
**New Conversations Report**
12341244
- **Endpoint**: `GET /v2/reports/conversations/new`
1245+
- **Required Parameters**: `start`, `end`
1246+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`
1247+
- **View Options**: `viewBy` (day ≤60 days, week ≤1 year, month ≥61 days)
1248+
- **Response**: Time-series data showing new conversation counts
1249+
- **Features**: Period comparison between current and previous intervals
1250+
1251+
**New Conversations Drilldown**
1252+
- **Endpoint**: `GET /v2/reports/conversations/new-drilldown`
1253+
- **Required Parameters**: `start`, `end`
1254+
- **Optional Parameters**: `mailboxes`, `tags`, `types`, `folders`, `page`, `rows` (max 50)
1255+
- **Response**: Detailed conversation list with pagination
1256+
- **Use Case**: Detailed breakdown of new conversations instead of just statistics
12351257

12361258
**Received Messages Report**
12371259
- **Endpoint**: `GET /v2/reports/conversations/received-messages`
1260+
- **Required Parameters**: `start`, `end`
1261+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`
1262+
- **View Options**: `viewBy` (day ≤60 days, week ≤1 year, month ≥61 days)
1263+
- **Response**: Time-series data showing customer message volumes (excludes agent replies)
1264+
- **Note**: Only counts messages from customers, not agent responses
12381265

12391266
**Conversations Drilldown**
12401267
- **Endpoint**: `GET /v2/reports/conversations/drilldown`
1268+
- **Required Parameters**: `start`, `end`
1269+
- **Optional Parameters**: `mailboxes`, `tags`, `types`, `folders`, `page`, `rows` (max 50)
1270+
- **Response**: Detailed conversation list with full metadata and pagination
1271+
- **Use Case**: Comprehensive conversation analysis with filtering
1272+
1273+
**Conversations Field Drilldown**
1274+
- **Endpoint**: `GET /v2/reports/conversations/fields-drilldown`
1275+
- **Required Parameters**: `start`, `end`, `field` (tagid/replyid/workflowid/customerid), `fieldid`
1276+
- **Optional Parameters**: `mailboxes`, `tags`, `types`, `folders`, `page`, `rows` (max 50)
1277+
- **Response**: Conversation data filtered by specific field values
1278+
- **Use Case**: Analysis of conversations by specific tags, saved replies, workflows, or customers
12411279

12421280
##### User Reports
12431281

12441282
**User Overall Report**
12451283
- **Endpoint**: `GET /v2/reports/user`
1284+
- **Required Parameters**: `user` (User ID), `start`, `end`
1285+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`, `officeHours`
1286+
- **Metrics**: Conversations created/resolved, replies sent, response/resolution times, happiness score, handle time, busiest day
1287+
- **Features**: Current vs previous period comparison with percentage changes
12461288

12471289
**User Conversation History**
12481290
- **Endpoint**: `GET /v2/reports/user/conversation-history`
1291+
- **Required Parameters**: `user` (User ID), `start`, `end`
1292+
- **Optional Parameters**: `status`, `mailboxes`, `tags`, `types`, `folders`
1293+
- **Sorting**: `sortField` (number, repliesSent, responseTime, resolveTime), `sortOrder` (ASC/DESC)
1294+
- **Response**: Detailed conversation list with performance metrics, pagination support
1295+
- **Use Case**: Drill-down analysis of specific user's conversation activity
12491296

12501297
**User Customers Helped**
12511298
- **Endpoint**: `GET /v2/reports/user/customers-helped`
1299+
- **Required Parameters**: `user` (User ID), `start`, `end`
1300+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`
1301+
- **View Options**: `viewBy` (day ≤60 days, week ≤1 year, month ≥61 days)
1302+
- **Response**: Time-series data showing customers helped per period
1303+
- **Example**: `[{"date": "2016-08-01T12:00:00Z", "customers": 29}]`
12521304

12531305
**User Happiness Report**
12541306
- **Endpoint**: `GET /v2/reports/user/happiness`
1307+
- **Required Parameters**: `user` (User ID), `start`, `end`
1308+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`
1309+
- **Metrics**: Rating percentages (Great/Okay/Not Good), customer counts, happiness score
1310+
- **Calculation**: Happiness Score = Great% - Not Good%
1311+
- **Features**: Period comparison with delta calculations
1312+
1313+
**User Happiness Drilldown**
1314+
- **Endpoint**: `GET /v2/reports/user/ratings`
1315+
- **Required Parameters**: `user` (User ID), `start`, `end`
1316+
- **Optional Parameters**: `mailboxes`, `tags`, `types`, `folders`, `rating` (great/ok/not-good/all)
1317+
- **Sorting**: `sortField` (number, modifiedAt, rating), `sortOrder` (ASC/DESC)
1318+
- **Response**: Individual rating entries with conversation details, customer/user metadata
1319+
- **Use Case**: Detailed analysis of specific satisfaction ratings
12551320

12561321
**User Replies Report**
12571322
- **Endpoint**: `GET /v2/reports/user/replies`
1323+
- **Required Parameters**: `user` (User ID), `start`, `end`
1324+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`
1325+
- **View Options**: `viewBy` with time range restrictions (day/week/month)
1326+
- **Response**: Time-series data showing replies sent per period
1327+
- **Example**: `[{"date": "2016-07-01T12:00:00Z", "replies": 15}]`
12581328

12591329
**User Resolutions Report**
12601330
- **Endpoint**: `GET /v2/reports/user/resolutions`
1331+
- **Required Parameters**: `user` (User ID), `start`, `end`
1332+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`
1333+
- **View Options**: `viewBy` (day ≤60 days, week ≤1 year, month ≥61 days)
1334+
- **Response**: Time-series data showing conversations resolved per period
1335+
- **Example**: `[{"date": "2017-01-01T12:00:00Z", "resolved": 18}]`
1336+
1337+
##### Productivity Reports
1338+
1339+
**Productivity Overall Report**
1340+
- **Endpoint**: `GET /v2/reports/productivity`
1341+
- **Required Parameters**: `start`, `end`
1342+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`, `officeHours`
1343+
- **Metrics**: Total conversations, resolution time, replies to resolve, response time, first response time, resolved conversations, closed conversations, replies sent, handle time
1344+
- **Features**: Period comparison, percentage changes, detailed time range distributions
1345+
1346+
**First Response Time Report**
1347+
- **Endpoint**: `GET /v2/reports/productivity/first-response-time`
1348+
- **Required Parameters**: `start`, `end`
1349+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`, `officeHours`
1350+
- **View Options**: `viewBy` (day ≤60 days, week ≤1 year, month ≥61 days)
1351+
- **Response**: Time-series data showing first response time durations
1352+
- **Example**: `[{"date": "2016-07-01T12:00:00Z", "time": "02:15:30"}]`
1353+
1354+
**Replies Sent Report**
1355+
- **Endpoint**: `GET /v2/reports/productivity/replies-sent`
1356+
- **Required Parameters**: `start`, `end`
1357+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`, `officeHours`
1358+
- **View Options**: `viewBy` (day ≤60 days, week ≤1 year, month ≥61 days)
1359+
- **Response**: Time-series data showing reply volumes
1360+
- **Example**: `[{"date": "2014-01-01T12:00:00Z", "replies": 636}]`
1361+
1362+
**Resolution Time Report**
1363+
- **Endpoint**: `GET /v2/reports/productivity/resolution-time`
1364+
- **Required Parameters**: `start`, `end`
1365+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`, `officeHours`
1366+
- **View Options**: `viewBy` (day ≤60 days, week ≤1 year, month ≥61 days)
1367+
- **Response**: Time-series data showing average resolution times
1368+
- **Use Case**: Track resolution performance trends over time
1369+
1370+
**Resolved Conversations Report**
1371+
- **Endpoint**: `GET /v2/reports/productivity/resolved`
1372+
- **Required Parameters**: `start`, `end`
1373+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`, `officeHours`
1374+
- **View Options**: `viewBy` (day ≤60 days, week ≤1 year, month ≥61 days)
1375+
- **Response**: Time-series data showing resolved conversation counts
1376+
- **Example**: `[{"date": "2014-01-01T12:00:00Z", "resolved": 14}]`
1377+
1378+
**Response Time Report**
1379+
- **Endpoint**: `GET /v2/reports/productivity/response-time`
1380+
- **Required Parameters**: `start`, `end`
1381+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`, `officeHours`
1382+
- **View Options**: `viewBy` (day ≤60 days, week ≤1 year, month ≥61 days)
1383+
- **Response**: Time-series data showing response time durations
1384+
- **Note**: Requires office hours to be enabled when using `officeHours` parameter
1385+
1386+
##### Happiness Reports
1387+
1388+
**Happiness Overall Report**
1389+
- **Endpoint**: `GET /v2/reports/happiness`
1390+
- **Required Parameters**: `start`, `end`
1391+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`
1392+
- **Metrics**: Rating percentages (Great/Okay/Not Good), happiness score, customer counts
1393+
- **Calculation**: Happiness Score = Great% - Not Good%
1394+
- **Features**: Period comparison with delta calculations
1395+
1396+
**Happiness Ratings Drilldown**
1397+
- **Endpoint**: `GET /v2/reports/happiness/ratings`
1398+
- **Required Parameters**: `start`, `end`
1399+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`, `rating` (great/ok/not-good/all)
1400+
- **Sorting**: `sortField` (number, modifiedAt, rating), `sortOrder` (ASC/DESC)
1401+
- **Pagination**: `page` parameter supported
1402+
- **Response**: Individual rating entries with conversation details, customer/user metadata
1403+
- **Use Case**: Detailed analysis of specific satisfaction ratings
12611404

12621405
##### Company Reports
12631406

12641407
**Company Overall Report**
12651408
- **Endpoint**: `GET /v2/reports/company`
1409+
- **Required Parameters**: `start`, `end`
1410+
- **Optional Parameters**: `previousStart`, `previousEnd`, `mailboxes`, `tags`, `types`, `folders`
1411+
- **Metrics**: Customers helped, conversations closed, total replies, total active users, replies per day, resolved conversations per day
1412+
- **Features**: User-specific performance breakdown, happiness score calculation, percentage changes
12661413

12671414
**Company Customers Helped**
12681415
- **Endpoint**: `GET /v2/reports/company/customers-helped`

0 commit comments

Comments
 (0)