Send Lab Visit Results SMS (v1)
Method & Path
POST /api/v1/workspace/:workspaceId/labs/visits/:labVisitId/send-sms
Actual backend path: /v1/workspace/:workspaceId/labs/visits/:labVisitId/send-sms
Description
Sends an SMS to the patient with a public link to view/print the lab visit results.
The message body is provided by the frontend (user-editable). The backend only:
- Chooses the recipient number from patient
contactMethods - Charges SMS cost based on the message length rules
The recipient number is auto-selected from the patient contactMethods:
- Prefer
phone, fallback towhatsapp
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": "Your results are ready. Please visit https://app.placio.app/public/labs/visits/<token>/print to view them."
}
Notes:
messageis 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.viewpermission - 404 Not Found: Workspace, lab visit, or client not found
- 422 Unprocessable Entity: No phone/WhatsApp contact method found for the client, or SMS balance/provider constraints
- 500 Internal Server Error: SMS sending failure