Patient portal & messaging

After purchase, patients need three things: see where their treatment stands, talk to their care team, and (for some offerings) verify their identity. Tagada Rx ships all three as portal endpoints your storefront can skin however it likes — the Oakwell template’s /portal page is a full reference implementation.

Auth model: portal routes are scoped to the customer, not the merchant. The patient logs in with an email OTP which creates a CMS session; every portal call carries that session token (x-cms-token). With the Plugin SDK this is automatic once the customer has logged in via useLogin — no extra wiring.

The endpoints

All under /api/v1/rx/portal/*, CMS-session authenticated:

Endpoint	What it returns
`GET /rx/portal/cases`	The customer’s cases (status, product, amounts, `canMessage`)
`GET /rx/portal/cases/{caseId}`	One case + its lifecycle timeline (`events`)
`GET /rx/portal/cases/{caseId}/messages`	The patient ↔ care-team thread, relayed live from the clinical network
`POST /rx/portal/cases/{caseId}/messages`	Send a patient message (text + optional attachments)
`POST /rx/portal/cases/{caseId}/identity`	Upload a photo ID for identity verification

Access control is strict: a case is only visible if it belongs to the authenticated customer, and messaging requires the case to have a linked network patient (canMessage: true).

Messaging

The thread is relayed from the clinical network — Tagada stores no message bodies (PHI transit rule). Messages carry an author so you can style the bubbles:

{
  "messages": [
    {
      "externalMessageId": "msg_…",
      "channel": "patient",
      "author": "clinician",
      "authorName": "Dr. Smith",
      "text": "Hi Jane — your dosage looks right. Any side effects?",
      "files": [],
      "createdAt": "2026-07-16T22:30:00Z"
    }
  ]
}

Sending, with optional attachments (images, documents, audio, video — base64-encoded):

POST /api/v1/rx/portal/cases/rxcase_xxx/messages
{
  "text": "Here's the photo you asked for.",
  "attachments": [
    { "filename": "arm.jpg", "mimeType": "image/jpeg", "contentBase64": "…" }
  ]
}

Notifications

When the care team writes (clinician or support — patient-authored messages are filtered out), Tagada emails the patient a content-free notification — “You have a new message from your care team” — deep-linking to your portal page. The email never contains the message text.

This is why your storefront should have a stable portal URL: the notification links there. The Oakwell template registers /portal and the thank-you page links to it.

Identity verification

Offerings mapped with requiresIdVerification: true need a government photo ID before the clinician can prescribe. One call handles upload + attachment to the network patient:

POST /api/v1/rx/portal/cases/rxcase_xxx/identity
{
  "filename": "license.jpg",
  "mimeType": "image/jpeg",
  "contentBase64": "…"
}

Show the upload block whenever the case’s offering requires it and the case is still pre-approval — the Oakwell portal renders it inline in the case detail view.

Plugin SDK wiring (Oakwell pattern)

import { useTagada, useLogin } from '@tagadapay/plugin-sdk/react';
import { createPortalClient, fileToAttachment } from '@/lib/portal-client';

function Portal() {
  const { apiService } = useTagada();
  const { isAuthenticated, sendOtp, verifyOtp } = useLogin();
  const portal = useMemo(() => createPortalClient(apiService), [apiService]);

  // 1. OTP gate
  if (!isAuthenticated) return <OtpLogin onSend={sendOtp} onVerify={verifyOtp} />;

  // 2. Then everything just works:
  //    portal.listCases()
  //    portal.getCase(caseId)          → { case, events } timeline
  //    portal.listMessages(caseId)
  //    portal.sendMessage(caseId, { text, attachments })
  //    portal.uploadIdentity(caseId, await fileToAttachment(file))
}

From a headless site, call the same endpoints with the CMS session token you obtain from the customer OTP login flow (tagada.customer module), passed as the x-cms-token header.

UX checklist for a good portal

Timeline, not jargon — render case.in_review as “A clinician is reviewing your information”, with dates.
Message composer with attachments — patients often need to send photos; accept camera capture on mobile.
ID upload prompt — surface it prominently while the case waits on identity verification; it’s the #1 stall cause.
Content-free everywhere — never mirror message text into your own emails, analytics, or logs.

Get Started

Activate

Build

Patients

Partners

Reference

Patient portal & messaging

Patient portal & messaging

The endpoints

Messaging

Notifications

Identity verification

Plugin SDK wiring (Oakwell pattern)

UX checklist for a good portal

​Patient portal & messaging

​The endpoints

​Messaging

​Notifications

​Identity verification

​Plugin SDK wiring (Oakwell pattern)

​UX checklist for a good portal

Patient portal & messaging

The endpoints

Messaging

Notifications

Identity verification

Plugin SDK wiring (Oakwell pattern)

UX checklist for a good portal