EHR / EMR Integration

This guide walks through connecting an EHR or EMR system to VitaRelay to automate the escript-to-fulfillment workflow.

What you’ll build

Push patients and intakes from your EHR into VitaRelay
Receive fulfillment status updates (order shipped, delivered) back in your system
Keep patient records in sync

Prerequisites

A VitaRelay API key issued by a VitaRelay admin (vr_live_… or vr_test_…) with the write scopes your integration needs
An HTTPS URL to receive webhook events, configured for your org by a VitaRelay admin

Step 1 — Create the patient

You don’t need to look up existing patients — POST /patients is idempotent on external_patient_id, so re-sending returns the original patient.

curl -X POST https://vitarelay.com/api/public/v1/patients \
  -H "Authorization: Bearer vr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_patient_id": "ehr-patient-4821",
    "first_name": "Jane",
    "last_name": "Smith",
    "dob": "1985-04-12",
    "email": "jane.smith@example.com",
    "phone": "+18135550100"
  }'

Use your own EHR record id as external_patient_id. A replay with the same id and the same body returns the original record (200 instead of 201); the same id with a different body returns 409 duplicate_request. Store the returned patient id (a UUID) against your local patient record.

Step 2 — Submit the intake

curl -X POST https://vitarelay.com/api/public/v1/intakes \
  -H "Authorization: Bearer vr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_intake_id": "ehr-intake-4821",
    "patient_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
    "category": "weight_management",
    "responses": {
      "height_in": 65,
      "weight_lb": 198,
      "goal": "weight loss",
      "current_medications": ["lisinopril"]
    }
  }'

When a prescriber signs the resulting escript, VitaRelay fires intake.reviewed.

Step 3 — Get your webhook endpoint configured

Webhook endpoints are not self-registered through the API. Give your VitaRelay admin the HTTPS URL that should receive events and the events you want (order.paid, order.shipped, order.delivered, order.exception, intake.reviewed). The admin configures it in the dashboard and shows you the signing secret once — store it in your secret manager.

Step 4 — Handle incoming events

In your EHR’s webhook handler:

export async function POST(request: Request) {
  const rawBody = await request.text();

  if (!verifyVitaRelaySignature(rawBody, request.headers.get("X-VitaRelay-Signature"), secret)) {
    return new Response("Unauthorized", { status: 401 });
  }

  const event = JSON.parse(rawBody);

  switch (event.event) {
    case "intake.reviewed":
      await markPrescriptionSigned(event.escript_id, event.patient_id);
      break;

    case "order.shipped":
      await updatePatientChartOrderStatus(event.order_id, "shipped", {
        trackingNumber: event.tracking_number,
        carrier: event.tracking_carrier,
      });
      break;

    case "order.delivered":
      await updatePatientChartOrderStatus(event.order_id, "delivered", {});
      break;
  }

  return new Response("OK", { status: 200 });
}

See Webhook Security for the verification helper.

Flow diagram

EHR captures patient + intake
        ↓
POST /api/public/v1/patients (find or create)
        ↓
POST /api/public/v1/intakes
        ↓
Prescriber signs → webhook: intake.reviewed
        ↓
POST /api/public/v1/orders → webhook: order.paid
        ↓
Pharmacy fulfills → webhook: order.shipped / order.delivered
        ↓
EHR updates patient chart

Getting Started

Webhooks

Guides

EHR Integration Guide

EHR / EMR Integration

What you’ll build

Prerequisites

Step 1 — Create the patient

Step 2 — Submit the intake

Step 3 — Get your webhook endpoint configured

Step 4 — Handle incoming events

Flow diagram

​EHR / EMR Integration

​What you’ll build

​Prerequisites

​Step 1 — Create the patient

​Step 2 — Submit the intake

​Step 3 — Get your webhook endpoint configured

​Step 4 — Handle incoming events

​Flow diagram

EHR / EMR Integration

What you’ll build

Prerequisites

Step 1 — Create the patient

Step 2 — Submit the intake

Step 3 — Get your webhook endpoint configured

Step 4 — Handle incoming events

Flow diagram