Advanced Patterns
Generating Visit History Summaries
Synthesize multiple past visit notes into concise clinical summaries for referrals, care transitions, and patient portals.
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 a visit summary
The visit summary endpoint synthesizes information from multiple past encounters into a single clinical narrative. It takes an array of past visit notes (SOAP notes, free-text summaries, or both) and produces a unified summary with key findings and active diagnoses. This is useful for referral letters, care transitions, patient portal summaries, and prior authorization support.
Use cases
- Referral letters -- Summarize a patient course across multiple visits for a specialist referral.
- Care transitions -- Generate handoff summaries when a patient transfers between providers or facilities.
- Patient portal summaries -- Create plain-language summaries patients can read to understand their care history.
- Prior authorization -- Compile treatment history and progress to support insurance authorization requests.
- Multi-provider synthesis -- Combine notes from different specialties (PCP, PT, psychiatrist) into a coherent clinical picture.
Request format
Send a POST request to /v1/visit-summary with an array of past visits. Each visit can include a free-text summary, a structured SOAP note, or both. You can optionally include patient_info and a focus area.
cURL
Terminal
curl -X POST https://api.soapnoteapi.com/v1/visit-summary \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"patient_info": {
"name": "Robert Kim",
"age": 58,
"gender": "male",
"medical_history": "Type 2 diabetes, hypertension, chronic low back pain"
},
"visits": [
{
"visit_date": "2026-01-10",
"provider": "Dr. Thompson (PCP)",
"soap_note": {
"subjective": "Patient presents for diabetes follow-up. Reports good adherence to metformin. Occasional fasting glucose readings above 150.",
"objective": "BP 138/88. A1c 7.4%. BMI 31.2. Foot exam normal.",
"assessment": "Type 2 diabetes, suboptimally controlled. Hypertension, above goal.",
"plan": "Increase metformin to 1000mg BID. Add amlodipine 5mg for blood pressure. Recheck A1c in 3 months. Referral to nutritionist."
},
"icd10_codes": ["E11.65", "I10"]
},
{
"visit_date": "2026-02-14",
"provider": "Dr. Thompson (PCP)",
"soap_note": {
"subjective": "Follow-up. Tolerating increased metformin. Blood pressure improved per home readings. Reports increased lower back pain with prolonged sitting at work.",
"objective": "BP 128/82. Weight stable. Lumbar ROM limited in flexion.",
"assessment": "Diabetes improving on adjusted regimen. Hypertension responding to amlodipine. Chronic low back pain, worsening.",
"plan": "Continue current medications. Physical therapy referral for low back pain. Follow up in 6 weeks with repeat A1c."
},
"icd10_codes": ["E11.65", "I10", "M54.5"]
},
{
"visit_date": "2026-03-01",
"provider": "Dr. Patel (Physical Therapy)",
"summary": "PT initial evaluation. Lumbar flexion 40 degrees (normal 60). Extension 15 degrees. Strength 4/5 bilateral lower extremities. Core weakness identified. Started on stabilization exercise program 2x/week for 6 weeks. Goals: increase flexion to 55 degrees, reduce pain to 3/10."
}
],
"focus": "overall health status with emphasis on diabetes management and back pain progression"
}'JavaScript
JavaScript
const response = await fetch("https://api.soapnoteapi.com/v1/visit-summary", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
patient_info: {
name: "Robert Kim",
age: 58,
gender: "male",
medical_history: "Type 2 diabetes, hypertension, chronic low back pain",
},
visits: [
{
visit_date: "2026-01-10",
provider: "Dr. Thompson (PCP)",
soap_note: {
Subjective: "Patient presents for diabetes follow-up...",
Objective: "BP 138/88. A1c 7.4%. BMI 31.2.",
Assessment: "Type 2 diabetes, suboptimally controlled.",
Plan: "Increase metformin to 1000mg BID. Add amlodipine 5mg.",
},
icd10_codes: ["E11.65", "I10"],
},
{
visit_date: "2026-02-14",
provider: "Dr. Thompson (PCP)",
soap_note: {
Subjective: "Tolerating increased metformin. BP improved.",
Objective: "BP 128/82. Lumbar ROM limited.",
Assessment: "Diabetes improving. Low back pain worsening.",
Plan: "Continue meds. PT referral for back pain.",
},
icd10_codes: ["E11.65", "I10", "M54.5"],
},
{
visit_date: "2026-03-01",
provider: "Dr. Patel (Physical Therapy)",
summary: "PT initial eval. Lumbar flexion 40 degrees. Core weakness. Started stabilization exercises.",
},
],
focus: "diabetes management and back pain progression",
}),
});
const summary = await response.json();
console.log(summary);Python
Python
import requests
response = requests.post(
"https://api.soapnoteapi.com/v1/visit-summary",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
json={
"patient_info": {
"name": "Robert Kim",
"age": 58,
"gender": "male",
},
"visits": [
{
"visit_date": "2026-01-10",
"provider": "Dr. Thompson (PCP)",
"soap_note": {
"subjective": "Diabetes follow-up...",
"objective": "BP 138/88. A1c 7.4%.",
"assessment": "Type 2 diabetes, suboptimally controlled.",
"plan": "Increase metformin. Add amlodipine.",
},
"icd10_codes": ["E11.65", "I10"],
},
{
"visit_date": "2026-02-14",
"provider": "Dr. Thompson (PCP)",
"soap_note": {
"subjective": "Tolerating increased metformin.",
"assessment": "Diabetes improving. Back pain worsening.",
"plan": "PT referral.",
},
},
{
"visit_date": "2026-03-01",
"provider": "Dr. Patel (PT)",
"summary": "PT initial eval. Core weakness. Started stabilization exercises.",
},
],
"focus": "diabetes management and back pain",
},
)
result = response.json()
print(result)Response format
The response includes a narrative summary, an array of key findings, and a list of active diagnoses with ICD-10 codes.
JSON
{
"summary": "Robert Kim is a 58-year-old male with type 2 diabetes mellitus, essential hypertension, and chronic low back pain. Over the past three months, his diabetes management has been optimized with increased metformin dosing (now 1000mg BID) and his A1c of 7.4% is trending toward goal. Hypertension is now well-controlled on amlodipine 5mg with blood pressure improving from 138/88 to 128/82. His chronic low back pain has worsened, prompting a physical therapy referral. Initial PT evaluation revealed limited lumbar flexion (40 degrees, goal 55) and core weakness. He is currently in a 6-week stabilization exercise program. Next steps include repeat A1c in April and continued PT.",
"key_findings": [
"A1c 7.4% on metformin 1000mg BID -- suboptimal but improving",
"Blood pressure improved from 138/88 to 128/82 on amlodipine 5mg",
"Lumbar flexion limited to 40 degrees with core weakness identified",
"Currently in physical therapy 2x/week stabilization program"
],
"active_diagnoses": [
{ "code": "E11.65", "description": "Type 2 diabetes mellitus with hyperglycemia" },
{ "code": "I10", "description": "Essential hypertension" },
{ "code": "M54.5", "description": "Low back pain" }
]
}Request fields reference
- patient_info (optional) -- Patient demographics. Same structure as the note generation context.patient_info field.
- visits (required, 1-100 items) -- Array of past visit objects.
- visits[].visit_date (required) -- Date of the visit as a string (e.g., "2026-03-01").
- visits[].provider (optional) -- Provider name and specialty for attribution.
- visits[].summary (optional) -- Free-text visit summary, up to 50,000 characters.
- visits[].soap_note (optional) -- Structured SOAP note with subjective, objective, assessment, and plan fields.
- visits[].icd10_codes (optional, max 50) -- ICD-10 codes from the visit for diagnostic context.
- focus (optional, max 1,000 chars) -- A specific focus area for the summary (e.g., "medication changes", "pain management progression"). When provided, the summary emphasizes the specified topic.
Tip: Each visit should include at least a summary or a soap_note (or both). Visits with only a visit_date and no clinical content will be noted in the timeline but cannot contribute meaningful information to the summary.
Controlling summary focus
The focus field lets you steer the summary toward specific clinical topics. Without it, the summary covers all visits equally. With it, the summary prioritizes the specified area while still mentioning other relevant findings.
- "focus": "medication changes" -- Emphasizes medication titrations, additions, and discontinuations across visits.
- "focus": "pain management" -- Focuses on pain levels, treatments tried, and functional outcomes.
- "focus": "surgical clearance" -- Highlights cardiovascular risk, lab results, and comorbidity management relevant to surgical planning.
- "focus": "insurance prior authorization for physical therapy" -- Frames the summary to support medical necessity documentation.
Multi-provider synthesis
Visit summaries handle notes from multiple providers and specialties in a single request. Include the provider field on each visit so the summary can attribute findings appropriately. This is especially powerful for care coordination -- combining a PCP visit, PT evaluation, and specialist consultation into one coherent narrative.
Best practices
- Order visits chronologically. The summary is clearest when visits are in date order.
- Include ICD-10 codes when available. They help the AI model identify and track diagnoses across visits.
- Use focus for targeted summaries. A referral letter has different emphasis than a patient portal summary.
- Keep visits under 100 per request. For patients with extensive history, select the most relevant visits rather than sending everything.
- Visit summaries are billed at $0.10 each and count as a separate usage event. Check summaries_this_period in GET /v1/me for your current period count.
Need help? Contact support@soapnoteapi.com