API reference

Reports

Five read endpoints expose the same data that powers the admin reports UI: completion activity, badge compliance, and today's roll-up. Activity rows are completions only; an employee who has not finished a lesson produces no row.

Shared conventions

from, to, and date are yyyy-MM-dd calendar dates, inclusive on both ends.
The default window is the last 30 days: to defaults to today and from defaults to 29 days before to. Passing only one bound keeps the other default.
Paged endpoints default to page=1 and pageSize=100 and return the standard paged envelope.
Examples run as-is against the sandbox ("Acme Logistics") with the public key tbm_test_wWlSr6q-BPXUN67BPbzyVhR703QGmSlk34EEWGqRBtA.

The activity row

All three activity endpoints return rows of the same shape:

Field	Type	Description
`employeeId`	string (uuid)	Toolbox Minute's internal employee id.
`employeeName`	string	The employee's full name.
`externalId`	string or null	Your employee code; `null` if the employee has none.
`lessonName`	string	The completed lesson's title.
`lessonDate`	string	The scheduled day the completion counts for, `yyyy-MM-dd`.
`completedAtUtc`	string	When the lesson was finished, UTC ISO 8601.
`topic`	string or null	The lesson's topic.
`subTopic`	string or null	The lesson's subtopic.
`quizScorePercent`	number	Quiz score, 0 to 100.

One employee's activity

GET /api/v1/reports/employees/{externalId}/activity

One employee's completion history over a date range. Returns a plain JSON array of activity rows (one employee over a bounded range stays small, so this endpoint is not paged).

Parameter	Type	Description
`externalId`	string (path)	The employee's external id.
`from`	date, optional	Range start. Defaults to 29 days before `to`.
`to`	date, optional	Range end. Defaults to today.

Request

curl -H "X-Api-Key: tbm_test_wWlSr6q-BPXUN67BPbzyVhR703QGmSlk34EEWGqRBtA" \
  "https://toolboxminute.com/api/v1/reports/employees/E-1001/activity?from=2026-07-13&to=2026-07-15"

Response

# HTTP/1.1 200 OK
[
  {
    "employeeId": "3c2d1a9b-5e6f-4a7c-8d9e-0f1a2b3c4d5e",
    "employeeName": "Dana Worker",
    "externalId": "E-1001",
    "lessonName": "Pre-Shift Inspection",
    "lessonDate": "2026-07-13",
    "completedAtUtc": "2026-07-13T13:04:11+00:00",
    "topic": "Powered Equipment",
    "subTopic": "Forklift Safety",
    "quizScorePercent": 100
  },
  {
    "employeeId": "3c2d1a9b-5e6f-4a7c-8d9e-0f1a2b3c4d5e",
    "employeeName": "Dana Worker",
    "externalId": "E-1001",
    "lessonName": "Load Limits & Stability",
    "lessonDate": "2026-07-14",
    "completedAtUtc": "2026-07-14T12:47:02+00:00",
    "topic": "Powered Equipment",
    "subTopic": "Forklift Safety",
    "quizScorePercent": 80
  }
]

Errors

# HTTP/1.1 404 Not Found
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "unknown_user",
  "status": 404,
  "detail": "No employee for external id 'E-9999'."
}

Company activity over a range

GET /api/v1/reports/activity

All employees' completions over a date range, paged.

Parameter	Type	Description
`from`	date, optional	Range start. Defaults to 29 days before `to`.
`to`	date, optional	Range end. Defaults to today.
`page`	number, optional	1-based page number. Defaults to 1.
`pageSize`	number, optional	Rows per page. Defaults to 100.

Request

curl -H "X-Api-Key: tbm_test_wWlSr6q-BPXUN67BPbzyVhR703QGmSlk34EEWGqRBtA" \
  "https://toolboxminute.com/api/v1/reports/activity?from=2026-06-16&to=2026-07-15&page=1&pageSize=100"

Response

# HTTP/1.1 200 OK
{
  "items": [
    {
      "employeeId": "9a8b7c6d-5e4f-4d3c-b2a1-0e9f8d7c6b5a",
      "employeeName": "Miguel Herrera",
      "externalId": "E-1002",
      "lessonName": "Pedestrian Awareness",
      "lessonDate": "2026-07-15",
      "completedAtUtc": "2026-07-15T11:58:40+00:00",
      "topic": "Powered Equipment",
      "subTopic": "Forklift Safety",
      "quizScorePercent": 100
    }
    /* ...more rows... */
  ],
  "page": 1,
  "pageSize": 100,
  "total": 164
}

Company activity for one day

GET /api/v1/reports/activity/daily

All employees' completions for a single day, paged. Same envelope and row shape as the range endpoint above.

Parameter	Type	Description
`date`	date, optional	The day to report. Defaults to today (the current UTC date).
`page`	number, optional	1-based page number. Defaults to 1.
`pageSize`	number, optional	Rows per page. Defaults to 100.

Request

curl -H "X-Api-Key: tbm_test_wWlSr6q-BPXUN67BPbzyVhR703QGmSlk34EEWGqRBtA" \
  "https://toolboxminute.com/api/v1/reports/activity/daily?date=2026-07-15"

Badge compliance

GET /api/v1/reports/badges

Badge status counts plus the badges expiring within a window, so you can prompt refresher training before coverage lapses.

Parameter	Type	Description
`withinDays`	number, optional	Expiry window in days. Defaults to 30.

Response fields

Field	Type	Description
`status.active`	number	Badges currently in force.
`status.expired`	number	Badges past their expiry.
`expiring`	array	Badges expiring within `withinDays`, one row per badge.
`expiring[].employeeId`	string (uuid)	Toolbox Minute's internal employee id.
`expiring[].employeeName`	string	The employee's full name.
`expiring[].subTopic`	string	The subtopic the badge certifies.
`expiring[].expiresAtUtc`	string	When the badge expires, UTC ISO 8601.

Request

curl -H "X-Api-Key: tbm_test_wWlSr6q-BPXUN67BPbzyVhR703QGmSlk34EEWGqRBtA" \
  "https://toolboxminute.com/api/v1/reports/badges?withinDays=30"

Response

# HTTP/1.1 200 OK
{
  "status": { "active": 5, "expired": 2 },
  "expiring": [
    {
      "employeeId": "9a8b7c6d-5e4f-4d3c-b2a1-0e9f8d7c6b5a",
      "employeeName": "Miguel Herrera",
      "subTopic": "Forklift Safety",
      "expiresAtUtc": "2026-07-29T00:00:00+00:00"
    }
  ]
}

Today's compliance summary

GET /api/v1/reports/compliance

Today's roll-up, the same numbers as the admin dashboard. Poll it to power a wallboard or a BI tile. No parameters.

Response fields

Field	Type	Description
`activeEmployees`	number	Active employees on the roster.
`completedToday`	number	Employees who finished today's lesson.
`expectedToday`	number	Employees with a lesson due today.
`compliancePercentToday`	number	Completed over expected, 0 to 100. May be fractional.
`activeBadges`	number	Badges currently in force.
`expiringSoon`	number	Badges expiring soon (30 day window).

Request

curl -H "X-Api-Key: tbm_test_wWlSr6q-BPXUN67BPbzyVhR703QGmSlk34EEWGqRBtA" \
  "https://toolboxminute.com/api/v1/reports/compliance"

Response

# HTTP/1.1 200 OK
{
  "activeEmployees": 8,
  "completedToday": 7,
  "expectedToday": 8,
  "compliancePercentToday": 87.5,
  "activeBadges": 5,
  "expiringSoon": 1
}