Note Generation

Improving Notes with Clinical Context

Pass patient demographics, clinical history, and billing code preferences to generate more accurate, complete SOAP notes.

Updated March 18, 2026

Note: Clinical accuracy disclaimer: All generated notes must be reviewed by a licensed healthcare provider before use in patient care. Example outputs in this guide are illustrative.

What is clinical context

The context object is an optional field on POST /v1/note and PUT /v1/note/audio that provides patient demographics, medical history, telehealth chat messages, and custom instructions alongside the transcript. It gives the AI model the background information a provider would have when writing a note -- resulting in more accurate, complete, and clinically relevant SOAP notes.

Why context matters

Without context, the AI generates a note solely from the transcript. With context, it can reference the patient by name, incorporate relevant medical history into the Assessment, reconcile current medications, and flag allergies in the Plan. The difference is the same as a provider seeing a new patient with no chart vs. a returning patient with a complete record.

Without context

JSON

{
  "transcript": "Patient reports knee pain for 2 weeks, worse with stairs. Taking something for it at home. Has had knee issues before.",
  "specialty": "primary_care_physician"
}

The generated note refers to "something for it at home" and "knee issues before" vaguely because the AI has no additional information to work with.

With context

JSON

{
  "transcript": "Patient reports knee pain for 2 weeks, worse with stairs. Taking something for it at home. Has had knee issues before.",
  "specialty": "primary_care_physician",
  "context": {
    "patient_info": {
      "name": "Maria Santos",
      "age": 62,
      "gender": "female",
      "medical_history": "Osteoarthritis bilateral knees diagnosed 2023, hypertension, type 2 diabetes",
      "medications": ["metformin 1000mg BID", "lisinopril 20mg daily", "ibuprofen 400mg PRN"],
      "allergies": ["sulfa drugs", "codeine"]
    },
    "patient_history": "Last visit 2025-12-10: Knee X-rays showed moderate medial compartment narrowing bilaterally. Tried physical therapy for 6 weeks with partial improvement."
  }
}

Now the AI can identify the "something" as ibuprofen from the medication list, reference the 2023 osteoarthritis diagnosis, note the prior PT course, flag the sulfa and codeine allergies when suggesting medications, and address the patient by name.

The context object

The context field accepts four optional sub-fields. You can include any combination.

patient_info

Structured patient demographics and clinical data.

JSON

"patient_info": {
  "name": "Maria Santos",
  "age": 62,
  "gender": "female",
  "medical_history": "Osteoarthritis, hypertension, type 2 diabetes",
  "medications": ["metformin 1000mg BID", "lisinopril 20mg daily"],
  "allergies": ["sulfa drugs", "codeine"]
}

name (string, max 200 chars) -- Patient name. Used in the note header and references.
age (integer, 0-200) -- Patient age in years.
gender (string, max 50 chars) -- Gender or sex for clinical context.
medical_history (string, max 50,000 chars) -- Free-text medical history, past diagnoses, surgical history.
medications (string array, max 100 items) -- Current medication list with dosages.
allergies (string array, max 100 items) -- Known allergies and adverse reactions.

patient_history

Free-text clinical history that does not fit into the structured patient_info fields. Use this for prior visit summaries, referral notes, relevant test results, or any background the provider would review before the encounter.

JSON

"patient_history": "Last visit 2025-12-10: Knee X-rays showed moderate medial compartment narrowing bilaterally. Tried PT for 6 weeks with partial improvement. Orthopedic referral recommended if symptoms persist. Labs from 2025-11: A1c 7.2%, eGFR 68."

Tip: patient_history supports up to 100,000 characters. Include as much relevant clinical history as you have -- the AI model will prioritize what is most relevant to the current encounter.

chat_messages

An array of chat messages from a telehealth session or patient intake form. Each message has a role (e.g., "provider", "patient"), content, and optional timestamp. This is useful for telehealth platforms that capture text chat alongside video.

JSON

"chat_messages": [
  {
    "role": "patient",
    "content": "I have been having sharp pains in my left knee going up stairs for about 2 weeks now.",
    "timestamp": "2026-03-18T09:00:00Z"
  },
  {
    "role": "provider",
    "content": "Any swelling or redness? Have you tried ice or anti-inflammatories?",
    "timestamp": "2026-03-18T09:01:00Z"
  },
  {
    "role": "patient",
    "content": "Some swelling after walking. I have been taking the ibuprofen you prescribed last time.",
    "timestamp": "2026-03-18T09:02:00Z"
  }
]

custom_instructions

Free-text instructions that guide the AI model during note generation. Use this for provider preferences, documentation style requirements, or specific clinical focus areas.

JSON

"custom_instructions": "Always include BMI in the objective section. Format the assessment as a numbered problem list with ICD-10 codes. Include patient education topics in the plan."

Note: custom_instructions supports up to 10,000 characters. Use it for documentation style preferences, required sections, or billing-specific formatting requirements.

Full example: chiropractic workers comp visit

This example shows all context fields used together for a chiropractic workers compensation case -- a scenario where clinical context significantly improves note quality and legal defensibility.

JavaScript

const response = await fetch("https://api.soapnoteapi.com/v1/note", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    transcript: "Patient returns for follow-up of lower back and neck pain from workplace injury. Reports pain level 5 out of 10, improvement from initial 8 out of 10. Lumbar flexion increased to 60 degrees. Cervical rotation improved bilaterally. Spinal adjustment performed at C5-C6 and L4-L5. Myofascial release to bilateral paraspinals.",
    specialty: "chiropractor",
    context: {
      patient_info: {
        name: "John Martinez",
        age: 45,
        gender: "male",
        medical_history: "Prior chiropractic care for lumbar strain 2022. History of spinal issues. No surgical history.",
        medications: ["ibuprofen 600mg TID"],
        allergies: [],
      },
      patient_history: "Date of injury: 2026-01-15. Mechanism: Slip and fall on wet floor at warehouse. Initial presentation: severe lower back and neck pain 8/10, limited ROM all planes. X-rays negative for fracture. MRI showed L4-L5 disc bulge without neural impingement. Workers comp claim filed. Treating 2x/week since 2026-01-22.",
      custom_instructions: "Include date of injury and mechanism of injury in the subjective section. Document functional improvement percentages for workers comp reporting. Include CPT codes for each procedure performed.",
    },
    include_billing_codes: true,
  }),
});

const note = await response.json();
console.log(note);

Python equivalent

Python

import requests

response = requests.post(
    "https://api.soapnoteapi.com/v1/note",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "transcript": "Patient returns for follow-up of lower back and neck pain from workplace injury. Reports pain level 5 out of 10, improvement from initial 8 out of 10. Lumbar flexion increased to 60 degrees. Cervical rotation improved bilaterally. Spinal adjustment performed at C5-C6 and L4-L5. Myofascial release to bilateral paraspinals.",
        "specialty": "chiropractor",
        "context": {
            "patient_info": {
                "name": "John Martinez",
                "age": 45,
                "gender": "male",
                "medical_history": "Prior chiropractic care for lumbar strain 2022. History of spinal issues.",
                "medications": ["ibuprofen 600mg TID"],
                "allergies": [],
            },
            "patient_history": "Date of injury: 2026-01-15. Mechanism: Slip and fall on wet floor at warehouse. Workers comp claim filed.",
            "custom_instructions": "Include date of injury and mechanism in subjective. Document functional improvement for workers comp.",
        },
        "include_billing_codes": True,
    },
)

note = response.json()
print(note)

Using context with audio uploads

For audio uploads via PUT /v1/note/audio, include the context in the metadata JSON field of the multipart request. The context is stored with the note and used during generation after the audio is transcribed.

JSON

{
  "filename": "visit-recording.m4a",
  "content_type": "audio/mp4",
  "specialty": "primary_care_physician",
  "context": {
    "patient_info": {
      "name": "Maria Santos",
      "age": 62,
      "gender": "female",
      "medications": ["metformin 1000mg BID", "lisinopril 20mg daily"]
    },
    "patient_history": "Follow-up for diabetes and hypertension management."
  }
}

Requesting billing codes and patient summaries

Two additional boolean flags work alongside context to enrich the output:

include_billing_codes: true -- Returns suggested ICD-10 and CPT codes derived from the note content. Codes are suggestions and must be verified by the billing provider.
include_patient_summary: true -- Returns a plain-language visit summary suitable for patient portals, after-visit summaries, or care coordination handoffs.

JSON

{
  "transcript": "...",
  "specialty": "primary_care_physician",
  "include_billing_codes": true,
  "include_patient_summary": true,
  "context": {
    "patient_info": { "name": "Maria Santos", "age": 62 }
  }
}

Billing codes in the response

JSON

{
  "noteId": "note_01jfg8h4kx9a3bc7d2ef",
  "subjective": "...",
  "objective": "...",
  "assessment": "...",
  "plan": "...",
  "billing_codes": {
    "icd10": [
      { "code": "M17.11", "description": "Primary osteoarthritis, right knee" },
      { "code": "I10", "description": "Essential hypertension" }
    ],
    "cpt": [
      { "code": "99214", "description": "Office visit, established patient, moderate complexity" }
    ]
  },
  "billing_codes_disclaimer": "Suggested codes are for reference only. Final code selection must be performed by a qualified healthcare professional.",
  "patient_summary": "You visited your doctor today for knee pain. Your doctor recommends continuing your current medications and starting physical therapy..."
}

Warning: Billing code suggestions are not a substitute for professional medical coding. Always have a qualified coder or provider verify the codes before submitting claims.

Best practices

Include as much context as you have. The model handles irrelevant context gracefully -- it is better to over-include than under-include.
Structured data beats free text. Use the patient_info fields (medications array, allergies array) rather than embedding everything in patient_history.
Keep custom_instructions focused. Specific instructions ("Include BMI in objective") produce better results than vague ones ("Make the note thorough").
Do not include the transcript content in context. The transcript and context are processed together -- duplicating information does not help.
Respect patient privacy. Only send the minimum context needed for note accuracy. Context is subject to the same data retention and HIPAA policies as the transcript.

Choosing the Right Specialty and Template Building Therapy Documentation

Need help? Contact support@soapnoteapi.com