​
Overview

The Audits API manages 5S workplace audit workflows. It covers two entity types: checklists (reusable assessment templates) and audit sessions (individual scored assessments conducted using a checklist). Low-scoring items can be automatically converted into tracked action items.

All procedures are tenant-scoped via organizationId and include audit trail logging.

​
Create Checklist

Create a new audit checklist template with assessment items organized by 5S category.

POST /api/trpc/audits.createChecklist

Request:

{
  "json": {
    "boardId": "brd_01HXK5...",
    "name": "Production Line A — 5S Checklist",
    "type": "5s",
    "items": [
      { "id": "item_01", "question": "All tools returned to designated locations", "category": "set_in_order", "maxScore": 5 },
      { "id": "item_02", "question": "Work surfaces clean and free of debris", "category": "shine", "maxScore": 5 },
      { "id": "item_03", "question": "Visual standards posted and current", "category": "standardize", "maxScore": 5 }
    ]
  }
}
FieldTypeRequiredDescription
boardIdstringYesBoard to associate the checklist with
namestringYesChecklist name
typestringYesChecklist type (e.g., 5s)
itemsarrayYesArray of assessment items
items[].idstringYesUnique item identifier within the checklist
items[].questionstringYesAssessment criterion text
items[].categorystringYes5S category: sort, set_in_order, shine, standardize, sustain
items[].maxScorenumberNoMaximum score for this item (default: 5)

​
Get Checklist

Retrieve a single checklist by ID with all its assessment items.

GET /api/trpc/audits.getChecklist?input={"json":{"id":"chk_01HXK5..."}}

​
List Checklists

List all audit checklists for a board.

GET /api/trpc/audits.listChecklists?input={"json":{"boardId":"brd_01HXK5..."}}

​
Start Audit

Start a new audit session using a checklist template. The session is created in in_progress status with the max possible score calculated from the checklist items.

POST /api/trpc/audits.startAudit

{
  "json": {
    "boardId": "brd_01HXK5...",
    "checklistId": "chk_01HXK5...",
    "date": "2026-03-25"
  }
}
FieldTypeRequiredDescription
boardIdstringYesBoard ID
checklistIdstringYesChecklist template to use
datestringNoAudit date (ISO 8601, defaults to today)

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "aud_01HXK5...",
        "checklistId": "chk_01HXK5...",
        "auditorId": "usr_01HXK5...",
        "date": "2026-03-25T00:00:00.000Z",
        "scores": [],
        "totalScore": 0,
        "maxScore": 15,
        "status": "in_progress"
      }
    }
  }
}

​
Submit Score

Score one or more checklist items during an active audit session. If a score for the same item already exists, it is replaced.

POST /api/trpc/audits.submitScore

{
  "json": {
    "sessionId": "aud_01HXK5...",
    "scores": [
      { "itemId": "item_01", "score": 4, "comment": "One tool missing from shadow board" },
      { "itemId": "item_02", "score": 5, "comment": null, "photoUrl": null },
      { "itemId": "item_03", "score": 2, "comment": "Visual standards outdated — last revision 6 months ago" }
    ]
  }
}
FieldTypeRequiredDescription
sessionIdstringYesAudit session ID
scoresarrayYesArray of item scores
scores[].itemIdstringYesChecklist item ID
scores[].scorenumberYesScore value (typically 1-5)
scores[].commentstringNoAuditor comment explaining the score
scores[].photoUrlstringNoURL of photo evidence

Scores are merged with existing session scores. Re-scoring the same item replaces the previous score. The total score is automatically recalculated after each submission.

​
Complete Audit

Finalize an audit session. Validates that all checklist items have been scored, then transitions the session to completed status.

POST /api/trpc/audits.completeAudit

{
  "json": {
    "id": "aud_01HXK5..."
  }
}

All checklist items must be scored before completing an audit. The API returns a 400 error listing the number of unscored items if completion is attempted prematurely.

​
List Audit Sessions

List audit sessions for a board with optional filters and pagination.

GET /api/trpc/audits.listAudits?input={"json":{"boardId":"brd_01HXK5...","status":"completed","limit":50,"offset":0}}
ParameterTypeRequiredDescription
boardIdstringYesBoard ID
checklistIdstringNoFilter by checklist template
statusstringNoin_progress or completed
limitnumberNoResults per page (1-200, default: 50)
offsetnumberNoPagination offset (default: 0)

Response:

{
  "result": {
    "data": {
      "json": {
        "items": [...],
        "total": 8,
        "hasMore": false
      }
    }
  }
}

​
Get Audit by ID

Retrieve a single audit session with all scores.

GET /api/trpc/audits.getAuditById?input={"json":{"id":"aud_01HXK5..."}}

​
Get Score History

Retrieve completed audit sessions with computed scores for trend analysis and radar charts.

GET /api/trpc/audits.getScoreHistory?input={"json":{"boardId":"brd_01HXK5...","checklistId":"chk_01HXK5...","limit":20}}
ParameterTypeRequiredDescription
boardIdstringYesBoard ID
checklistIdstringNoFilter by specific checklist
limitnumberNoMax sessions to return (1-100, default: 20)

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "aud_01HXK5...",
          "date": "2026-03-25T00:00:00.000Z",
          "totalScore": 11,
          "maxScore": 15,
          "percentage": 73,
          "categoryScores": {
            "overall": { "total": 11, "count": 3, "average": 3.7 }
          }
        }
      ]
    }
  }
}

​
Generate Actions

Create follow-up action items for checklist items that scored below a threshold.

POST /api/trpc/audits.generateActions

{
  "json": {
    "sessionId": "aud_01HXK5...",
    "threshold": 3
  }
}
FieldTypeRequiredDescription
sessionIdstringYesCompleted audit session ID
thresholdnumberNoScore threshold (1-5, default: 3). Items below this score generate actions.

Response:

{
  "result": {
    "data": {
      "json": {
        "actionsCreated": 1,
        "threshold": 3
      }
    }
  }
}

Actions are created with source = "audit", priority based on score severity (score 1 = high, score 2 = medium), and titles prefixed with [5S Audit] for easy identification in the action log.

Was this page helpful?

Problem SolvingAutomations