List Lab Visits (v1)

Method & Path

GET /api/v1/workspace/:workspaceId/labs/visits

Actual backend path: /v1/workspace/:workspaceId/labs/visits

Description

List lab visits in a workspace. Supports filtering by status, client, type, and date range with pagination.

Authentication

Required: JWT token in Authorization header

Persona Access:

• Admin: Not applicable (workspace-scoped endpoint)
• Workspace Owner: Allowed
• Staff: Allowed (role-based)
• Customer: Not allowed

Required Permissions:

• labs.view

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token: Bearer <token>

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier (MongoDB ObjectId)

Query Parameters

Parameter	Type	Required	Description
labVisitStatus	string	No	Filter by status: pending, in-progress, results-entered, invoiced, cancelled, ready
clientId	string	No	Filter by client (MongoDB ObjectId)
labVisitType	string	No	Filter by type: in-lab, at-home
startDate	string	No	ISO datetime (inclusive)
endDate	string	No	ISO datetime (inclusive)
limit	number	No	Page size (1-100). Default: 50
offset	number	No	Offset for pagination. Default: 0

Response 200 OK

{
  "labVisits": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439012",
      "clientId": "507f1f77bcf86cd799439013",
      "labVisitType": "in-lab",
      "labVisitStatus": "pending",
      "labTestIds": [101],
      "labTestSnapshots": [
        {
          "test": {
            "testId": 101,
            "testTitle": "CBC"
          },
          "designTest": null
        }
      ],
      "labTestResults": [],
      "labVisitDate": "2026-01-10T12:00:00.000Z",
      "labVisitNotes": null,
      "labVisitPricing": {
        "labVisitSubtotal": 30,
        "labCouponId": null,
        "labCouponCode": null,
        "labVisitDiscountAmount": 0,
        "labVisitTotal": 30
      },
      "deletedAt": null,
      "createdAt": "2026-01-10T12:00:00.000Z",
      "updatedAt": "2026-01-10T12:00:00.000Z"
    }
  ],
  "total": 1
}

note

labTestIds may be returned for convenience. You can also derive it from snapshots: labTestIds = labTestSnapshots.map((s) => s.test.testId).

Common Errors

400 Bad Request: Invalid query parameters (e.g., invalid date format)

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: Insufficient permissions (labs.view required)

404 Not Found: Workspace not found

422 Validation Error: Invalid workspace ID format or validation errors