Skip to main content
POST
/
alpha
/
note-templates
curl -X POST "https://api.sully.ai/alpha/note-templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "generate",
    "notes": [
      {
        "content": "Chief Complaint: Patient presents with chest pain.\n\nHistory of Present Illness: 45-year-old male with acute onset chest pain, radiating to left arm. Pain started 2 hours ago while at rest.\n\nPhysical Exam: Vital signs stable. Heart rate 88 bpm, BP 140/90.\n\nAssessment: Possible acute coronary syndrome.\n\nPlan: ECG, troponin levels, cardiology consult.",
        "description": "Cardiology consultation note"
      },
      {
        "content": "Chief Complaint: Shortness of breath.\n\nHistory of Present Illness: 67-year-old female with progressive dyspnea over 3 days. No chest pain.\n\nPhysical Exam: Crackles bilateral lower lobes. JVD present.\n\nAssessment: Congestive heart failure exacerbation.\n\nPlan: Chest X-ray, BNP, diuretics, follow-up in 48 hours.",
        "description": "Heart failure follow-up"
      }
    ],
    "instructions": "Focus on creating a template for cardiology consultations with emphasis on systematic assessment."
  }'

{
  "data": {
    "id": "template_abc123def456",
    "mode": "generate",
    "status": "pending",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

​
Overview

The unified note template endpoint supports two modes of operation:
  1. Generation Mode: Analyzes provider notes to automatically create customized note templates from scratch
  2. Refinement Mode: Improves existing templates based on instructions or before/after note comparisons
This helps standardize documentation while preserving your unique clinical style and preferred structure.

​
Request Body

The request body varies depending on the operation mode:

​
Generation Mode (Default)

​
mode
string
Set to “generate” (default) to create a template from provider notes
​
notes
array
required
Array of provider notes to analyze (minimum 1, maximum 5 notes per request)
​
instructions
string
Optional instructions for the template generation process

​
Refinement Mode

​
mode
string
required
Set to “refine” to improve an existing template
​
template
object
required
The existing note template to refine (must be a complete NoteTemplate object)
​
instructions
string
Instructions for how to refine the template
​
note_comparison
object
Before/after note comparison to guide refinement

​
Response

​
data
object
The created note template job
curl -X POST "https://api.sully.ai/alpha/note-templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "generate",
    "notes": [
      {
        "content": "Chief Complaint: Patient presents with chest pain.\n\nHistory of Present Illness: 45-year-old male with acute onset chest pain, radiating to left arm. Pain started 2 hours ago while at rest.\n\nPhysical Exam: Vital signs stable. Heart rate 88 bpm, BP 140/90.\n\nAssessment: Possible acute coronary syndrome.\n\nPlan: ECG, troponin levels, cardiology consult.",
        "description": "Cardiology consultation note"
      },
      {
        "content": "Chief Complaint: Shortness of breath.\n\nHistory of Present Illness: 67-year-old female with progressive dyspnea over 3 days. No chest pain.\n\nPhysical Exam: Crackles bilateral lower lobes. JVD present.\n\nAssessment: Congestive heart failure exacerbation.\n\nPlan: Chest X-ray, BNP, diuretics, follow-up in 48 hours.",
        "description": "Heart failure follow-up"
      }
    ],
    "instructions": "Focus on creating a template for cardiology consultations with emphasis on systematic assessment."
  }'

{
  "data": {
    "id": "template_abc123def456",
    "mode": "generate",
    "status": "pending",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

​
Status Codes

​
202
Accepted
Note template job created successfully and is being processed
​
400
Bad Request
Invalid request body, missing required fields, or validation errors
  • Generation Mode: Missing notes array, too many notes (maximum 5), empty note content, description too long (maximum 1000 characters)
  • Refinement Mode: Missing template object, invalid template structure, note comparison validation errors
  • Both Modes: Invalid mode value, malformed request structure
​
401
Unauthorized
Invalid or missing API key
​
500
Internal Server Error
Server error occurred while processing the request

​
Validation Rules

Input Validation: The following validation rules apply:Generation Mode:
  • Notes: Minimum 1, maximum 5 notes per request
  • Content: Required for each note, cannot be empty
  • Description: Optional, maximum 1000 characters per note
  • Instructions: Optional
Refinement Mode:
  • Template: Required, must be a valid NoteTemplate object
  • Instructions: Optional
  • Note Comparison: Optional, both before and after content required if provided
  • Description: Optional, maximum 1000 characters for note comparison

​
Next Steps

After creating a note template job:
  1. Poll for results: Use the Get Note Template endpoint with the returned ID to check status and retrieve results
  2. Use webhooks: Configure webhooks to get notified when processing completes (recommended)
  3. Clean up: Use the Delete Note Template endpoint to remove jobs you no longer need

​
Best Practices

​
Generation Mode

Note Selection:
  • Quality over quantity: Use your best, most representative notes
  • Consistency: Include notes with similar structure and style
  • Completeness: Use complete notes rather than fragments
  • Variety: Include different types of cases within the same specialty
Instructions:
  • Be specific: “Focus on cardiology consultations” vs. “Make a good template”
  • Mention priorities: “Emphasize differential diagnosis section”
  • Include preferences: “Use bullet points for assessment and plan”

​
Refinement Mode

Template Preparation:
  • Use existing templates: Start with a working template that needs improvement
  • Identify specific issues: Know what aspects need refinement
Instructions:
  • Be precise: “Add severity scoring to assessment section”
  • Reference sections: “Modify the plan section to include follow-up timeframes”
  • Specify changes: “Change from paragraph to bullet point format”
Note Comparisons:
  • Use real examples: Provide actual before/after note content
  • Show clear differences: Highlight specific improvements needed
  • Include context: Explain why the changes are desired

​
Example Instructions

Generation Mode
{
  "instructions": "Create a template for emergency department visits focusing on rapid assessment. Prioritize chief complaint, vital signs, and disposition. Use concise bullet points for efficiency."
}
Refinement Mode
{
  "instructions": "Enhance the assessment section to include severity scoring (1-10), differential diagnosis with at least 3 options, and risk stratification. Convert plan from paragraph to structured list format with categories: Diagnostics, Medications, Follow-up."
}