Create Lab Visit (v1)

Method & Path

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

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

Description

Create a new lab visit for a client and attach one or more lab tests.

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.run

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token: Bearer <token>
Content-Type	string	Yes	application/json

Path Parameters

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

Request Body

{
  "clientId": "507f1f77bcf86cd799439013",
  "referralId": "507f1f77bcf86cd799439099",
  "labVisitType": "in-lab",
  "labTestIds": [101, 205],
  "labVisitDate": "2026-01-10T12:00:00.000Z",
  "labVisitNotes": "Priority visit",
  "labCouponCode": "WINTER10",
  "labVisitSubtotal": null
}

Field	Type	Required	Description
clientId	string	Yes	Client identifier (MongoDB ObjectId)
referralId	string | null	No	Referral identifier (MongoDB ObjectId). When provided, must belong to the same workspace
labVisitType	string	Yes	in-lab or at-home
labTestIds	number[]	Yes	Array of test IDs (numeric)
labVisitDate	string	Yes	ISO datetime
labVisitNotes	string	No	Notes (max 2000 chars)
labCouponCode	string | null	No	Coupon code to apply
labVisitSubtotal	number | null	No	Optional subtotal. If omitted/null, backend calculates subtotal from test prices

Response 201 Created

{
  "labVisit": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f1f77bcf86cd799439012",
    "clientId": "507f1f77bcf86cd799439013",
    "referralId": "507f1f77bcf86cd799439099",
    "labVisitType": "in-lab",
    "labVisitStatus": "pending",
    "labTestIds": [101, 205],
    "labTestSnapshots": [
      {
        "test": { "testId": 101, "testTitle": "CBC" },
        "designTest": null
      },
      {
        "test": { "testId": 205, "testTitle": "CRP" },
        "designTest": null
      }
    ],
    "labTestResults": [],
    "labVisitDate": "2026-01-10T12:00:00.000Z",
    "labVisitNotes": "Priority visit",
    "labVisitPricing": {
      "labVisitSubtotal": 100,
      "labCouponId": "507f1f77bcf86cd799439055",
      "labCouponCode": "WINTER10",
      "labVisitDiscountAmount": 10,
      "labVisitTotal": 90
    },
    "deletedAt": null,
    "createdAt": "2026-01-10T12:00:00.000Z",
    "updatedAt": "2026-01-10T12:00:00.000Z"
  }
}

Common Errors

400 Bad Request: Invalid request body or missing required fields

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: Insufficient permissions (labs.run required)

404 Not Found: Workspace or client not found

422 Validation Error: Invalid IDs or validation errors (e.g., missing tests, invalid coupon)