How to Feed Patient Data to AI Models Safely: Building AI Scribes and Copilots with ClinikAPI

Quick Answer

AI clinical scribes and copilots are only as good as the data you feed them. Unstructured EHR data produces hallucinated, inaccurate notes. ClinikAPI strictly enforces FHIR R4 schemas, which means every patient record, encounter, observation, and prescription follows a consistent, predictable structure. When you feed this structured data to OpenAI, Anthropic, or any LLM, the model has clean context to generate highly accurate clinical notes, treatment plans, and summaries. The result: AI output that clinicians actually trust.

---

Why AI Scribes Need Structured Data

The biggest problem with AI clinical documentation is not the AI model — it is the data going in.

What happens with unstructured data:

• You feed the LLM a blob of free-text notes from a legacy EHR
• The model guesses at medication names, dosages, and diagnoses
• It hallucinates details that were not in the original text
• The clinician spends 10 minutes fixing errors — defeating the purpose

What happens with structured FHIR data:

• You feed the LLM a clean JSON object with typed fields
• Medications have exact names, dosages, and frequencies
• Diagnoses have ICD-10 codes
• Vitals have numeric values with units
• The model generates accurate, structured notes
• The clinician reviews and signs in 2 minutes

The difference is not the AI model. It is the data quality. ClinikAPI enforces FHIR R4 schemas on every write, which means every piece of clinical data in your system is structured, validated, and consistent. This is exactly what LLMs need to produce reliable output.

---

Architecture: AI Scribe with ClinikAPI

Here is how a typical AI scribe application works with ClinikAPI:

Clinician dictates session summary
    ↓
Your app captures the dictation
    ↓
Your app pulls patient context from ClinikAPI
(demographics, medications, recent encounters, vitals)
    ↓
Your app sends dictation + context to LLM (OpenAI, Anthropic, etc.)
    ↓
LLM generates structured SOAP note
    ↓
Clinician reviews and approves
    ↓
Your app saves the note to ClinikAPI (clinik.notes.create)

The key step is pulling patient context before sending to the LLM. Without context, the AI is guessing. With context, it is informed.

---

Step-by-Step: Building an AI Scribe

Step 1: Pull Patient Context from ClinikAPI

Before generating a note, pull the patient's current clinical context:

import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!);

// Get patient with all related clinical data
const { data } = await clinik.patients.read(patientId, {
  include: ['Encounter', 'Observation', 'MedicationRequest'],
});

const context = {
  patient: {
    name: `${data.patient.firstName} ${data.patient.lastName}`,
    age: calculateAge(data.patient.birthDate),
    gender: data.patient.gender,
  },
  currentMedications: data.prescriptions
    .filter((rx: any) => rx.status === 'active')
    .map((rx: any) => `${rx.medication} — ${rx.dosage}`),
  recentVitals: data.observations
    .slice(0, 5)
    .map((obs: any) => `${obs.code}: ${obs.value} ${obs.unit}`),
  recentEncounters: data.encounters
    .slice(0, 3)
    .map((enc: any) => `${enc.date}: ${enc.type}`),
};

This gives the LLM structured context: who the patient is, what medications they are on, their recent vitals, and their visit history. All from clean, FHIR-validated data.

Step 2: Build the LLM Prompt

Combine the clinician's dictation with the patient context:

const systemPrompt = `You are a clinical documentation assistant. 
Generate a structured SOAP note based on the clinician's session summary.
Use the patient context provided to ensure accuracy.
Do not hallucinate information not present in the summary or context.
Use professional clinical language.

PATIENT CONTEXT:
- Name: ${context.patient.name}
- Age: ${context.patient.age}, ${context.patient.gender}
- Current Medications: ${context.currentMedications.join(', ') || 'None'}
- Recent Vitals: ${context.recentVitals.join(', ') || 'None recorded'}
- Recent Visits: ${context.recentEncounters.join(', ') || 'None'}`;

const userPrompt = `SESSION SUMMARY:
${clinicianDictation}

Generate a SOAP note with Subjective, Objective, Assessment, and Plan sections.`;

Step 3: Call the LLM

import OpenAI from 'openai';

const openai = new OpenAI();

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: systemPrompt },
    { role: 'user', content: userPrompt },
  ],
  temperature: 0.3, // Lower temperature for clinical accuracy
});

const generatedNote = completion.choices[0].message.content;

Step 4: Save the Note to ClinikAPI

// Create an encounter for this session
const { data: encounter } = await clinik.encounters.create({
  patientId,
  practitionerId,
  type: 'therapy-session',
  status: 'finished',
});

// Save the AI-generated note (as preliminary — clinician must review)
const { data: note } = await clinik.notes.create({
  patientId,
  encounterId: encounter.id,
  type: 'soap-note',
  content: generatedNote,
  author: practitionerId,
  status: 'preliminary',
});

// After clinician reviews and approves:
await clinik.notes.update(note.id, { status: 'final' });

The note is now stored as a FHIR DocumentReference, linked to the patient and encounter, with a full audit trail.

---

Why FHIR Schemas Make AI Output Better

Here is a concrete example of the difference structured data makes.

Without structured data (free-text EHR):

The LLM receives: "Patient is on some blood pressure medication, maybe lisinopril or losartan, not sure of the dose. BP was high last visit."

The LLM generates: "Patient is currently taking lisinopril 20mg daily. Blood pressure was 150/95 at last visit."

Problem: The model guessed the medication, dose, and BP values. None of this may be accurate.

With ClinikAPI structured data:

The LLM receives:

{
  "currentMedications": ["Lisinopril 10mg — Take 1 tablet by mouth once daily"],
  "recentVitals": ["blood-pressure: 138/88 mmHg (2026-04-20)"]
}

The LLM generates: "Patient is currently taking Lisinopril 10mg daily. Blood pressure at last visit (April 20) was 138/88 mmHg, slightly elevated."

This is accurate because the model had exact, structured data to work with. No guessing. No hallucination.

---

Beyond Notes: Other AI Copilot Use Cases

Treatment Plan Suggestions

Pull a patient's diagnosis history and current medications, then ask the LLM to suggest evidence-based treatment options:

const { data: assessments } = await clinik.assessments.search({
  patientId,
});

const prompt = `Based on this patient's assessment history and current medications,
suggest evidence-based treatment plan adjustments:

Assessments: ${JSON.stringify(assessments.data)}
Current Meds: ${JSON.stringify(context.currentMedications)}`;

Patient Communication Drafts

Generate patient-friendly summaries of visit notes, lab results, or treatment plans:

const { data: labResults } = await clinik.labs.read(labId);

const prompt = `Write a patient-friendly explanation of these lab results.
Use simple language. Highlight any abnormal values and what they mean.

Lab Results: ${JSON.stringify(labResults)}`;

Clinical Decision Support

Feed the LLM a patient's complete clinical picture and ask for risk assessments or screening recommendations:

const { data } = await clinik.patients.read(patientId, {
  include: ['Observation', 'MedicationRequest', 'Encounter'],
});

const prompt = `Based on this patient's clinical data, identify any 
preventive screenings that are overdue or risk factors that need attention.

Patient Data: ${JSON.stringify(data)}`;

---

Safety and Compliance

Never Send PHI to Non-Compliant AI Services

If you are using OpenAI, Anthropic, or Google AI, make sure you are on a plan that offers a BAA (Business Associate Agreement). Consumer-tier AI services are not HIPAA-compliant.

• OpenAI: Enterprise and API plans offer BAAs
• Anthropic: Claude for Enterprise offers BAAs
• Google: Vertex AI offers BAAs

Always Mark AI Notes as Preliminary

AI-generated notes should always be saved with status: 'preliminary' until a clinician reviews and approves them. The clinician is legally responsible for the final note, not the AI.

Audit Everything

ClinikAPI automatically logs every API call. Your application should also log which AI model was used, what prompt was sent (without PHI in logs), and when the clinician approved the final note.

De-Identify When Possible

If your AI workflow does not need the patient's name or other identifiers, strip them before sending to the LLM. Use patient IDs instead of names in prompts.

---

Frequently Asked Questions

Which AI models work best for clinical documentation? OpenAI GPT-4o and Anthropic Claude 3.5 Sonnet both produce high-quality clinical notes. Use lower temperature settings (0.2-0.4) for clinical accuracy. The model matters less than the quality of the structured data you feed it.

Does ClinikAPI integrate directly with OpenAI or Anthropic? No — and that is by design. ClinikAPI handles clinical data storage and retrieval. Your application handles the AI integration. This separation keeps the architecture clean and lets you swap AI providers without changing your data layer.

How do I handle AI hallucinations in clinical notes? Three strategies: (1) Provide structured context from ClinikAPI so the model has accurate data to work with. (2) Use lower temperature settings. (3) Always require clinician review before finalizing notes. The preliminary → final status workflow in ClinikAPI enforces this.

Is it HIPAA-compliant to send patient data to an LLM? Only if the LLM provider signs a BAA. OpenAI Enterprise, Anthropic Enterprise, and Google Vertex AI offer BAAs. Consumer-tier AI services (ChatGPT Free/Plus, Claude Free) do not. Always verify before sending PHI.

Can I build an AI scribe without ClinikAPI? Yes, but you would need to build your own FHIR data layer, HIPAA compliance infrastructure, and structured data pipeline. ClinikAPI provides all of this out of the box, so you can focus on the AI logic.

How accurate are AI-generated clinical notes with structured data? With clean, structured FHIR data from ClinikAPI, AI-generated notes are typically 90-95% accurate on first draft. The remaining 5-10% requires clinician review for clinical nuance, subjective observations, and treatment decisions that the AI cannot infer from data alone.

---

Related Reading

• 5 Healthcare Apps You Can Build with ClinikAPI
• FHIR R4 Made Simple
• HIPAA Compliance for Developers
• Can You Use ChatGPT for Therapy Notes?
• Can You Use Claude AI for Therapy Notes?