Send Lab Visit Referral Results SMS (v1)

Method & Path

POST /api/v1/workspace/:workspaceId/labs/visits/:labVisitId/send-referral-sms

Actual backend path: /v1/workspace/:workspaceId/labs/visits/:labVisitId/send-referral-sms

Description

Sends an SMS to the referral (الإحالة) associated with the lab visit, containing a public link to view/print the lab visit results.

Notes:

• The lab visit must have referralId set.
• The recipient mobile is derived from the referral record (workspace-scoped).
• The message body is provided by the frontend (user-editable) and sent as-is.

Authentication

Required: JWT token in Authorization header

Persona Access:

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

Required Permissions:

• labs.view

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token: Bearer <token>
X-Staff-Id	string	No	Staff member ID (omit for Workspace Owner access)

Path Parameters

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

Request Body

{
  "message": "A new test issued for one of your patients. Please visit https://app.placio.app/public/labs/visits/<token>/print to view the results."
}

Notes:

• message is required and will be sent as-is.

Response 200 OK

{
  "success": true
}

Common Errors

• 400 Bad Request: Invalid identifiers or malformed request
• 401 Unauthorized: Missing/invalid JWT
• 403 Forbidden: Missing labs.view permission
• 404 Not Found: Workspace, lab visit, or referral not found
• 422 Unprocessable Entity: No referral set on the visit, referral has no valid phone, or SMS balance/provider constraints
• 500 Internal Server Error: SMS sending failure