> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sully.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Note Template Job

> Create a note template generation or refinement job to build or improve clinical documentation templates.

## 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)

<ParamField body="mode" type="string" optional>
  Set to "generate" (default) to create a template from provider notes
</ParamField>

<ParamField body="notes" type="array" required>
  Array of provider notes to analyze (minimum 1, maximum 5 notes per request)

  <Expandable title="Provider Note Object">
    <ParamField body="content" type="string" required>
      The content of the provider note
    </ParamField>

    <ParamField body="description" type="string" optional>
      Optional description of the note (max 1000 characters)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="instructions" type="string" optional>
  Optional instructions for the template generation process
</ParamField>

### Refinement Mode

<ParamField body="mode" type="string" required>
  Set to "refine" to improve an existing template
</ParamField>

<ParamField body="template" type="object" required>
  The existing note template to refine (must be a complete NoteTemplate object)
</ParamField>

<ParamField body="instructions" type="string" optional>
  Instructions for how to refine the template
</ParamField>

<ParamField body="note_comparison" type="object" optional>
  Before/after note comparison to guide refinement

  <Expandable title="Note Comparison Object">
    <ParamField body="before" type="string" required>
      The note content before applying the template
    </ParamField>

    <ParamField body="after" type="string" required>
      The desired note content after applying the template
    </ParamField>

    <ParamField body="description" type="string" optional>
      Optional description of what changed (max 1000 characters)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="data" type="object">
  The created note template job

  <Expandable title="Note Template Job Object">
    <ResponseField name="id" type="string">
      Unique identifier for the template job
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the job

      * `pending`: Job is queued for processing
      * `processing`: Currently processing the request
      * `completed`: Processing complete, results available
      * `failed`: Processing failed
    </ResponseField>

    <ResponseField name="mode" type="string">
      The operation mode for this job

      * `generate`: Creating a template from provider notes
      * `refine`: Improving an existing template
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Timestamp when the job was created (ISO 8601 format)
    </ResponseField>

    <ResponseField name="updated_at" type="string" optional>
      Timestamp when the job was last updated (ISO 8601 format)
    </ResponseField>

    <ResponseField name="result" type="object" optional>
      Available when status is "completed" - contains the generated/refined template

      <ResponseField name="template" type="object" optional>
        The generated or refined note template

        <Expandable title="Template Object">
          <ResponseField name="id" type="string">
            Unique identifier for the template
          </ResponseField>

          <ResponseField name="title" type="string">
            Title for the template
          </ResponseField>

          <ResponseField name="global_prompt" type="string" optional>
            Global prompt/instructions for the template
          </ResponseField>

          <ResponseField name="sections" type="array">
            Array of template sections with structure and prompts
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="error" type="string" optional>
        Error message if processing failed
      </ResponseField>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Generation Mode (cURL) theme={null}
  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."
    }'
  ```

  ```bash Refinement Mode (cURL) theme={null}
  curl -X POST "https://api.sully.ai/alpha/note-templates" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "mode": "refine",
      "template": {
        "id": "existing-template-123",
        "title": "Cardiology Consultation Template",
        "sections": [...]
      },
      "instructions": "Add more detailed assessment prompts and include differential diagnosis section",
      "note_comparison": {
        "before": "Assessment: Chest pain, likely cardiac.",
        "after": "Assessment: Acute chest pain syndrome with features suggestive of unstable angina. Differential includes NSTEMI, aortic dissection, and pulmonary embolism. Risk stratification indicates intermediate probability for ACS."
      }
    }'
  ```

  ```javascript Generation Mode (JavaScript) theme={null}
  const response = await fetch('https://api.sully.ai/alpha/note-templates', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      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."
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```javascript Refinement Mode (JavaScript) theme={null}
  const response = await fetch('https://api.sully.ai/alpha/note-templates', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      mode: 'refine',
      template: {
        id: 'existing-template-123',
        title: 'Cardiology Consultation Template',
        sections: [
          // ... existing template sections
        ]
      },
      instructions: 'Add more detailed assessment prompts and include differential diagnosis section',
      note_comparison: {
        before: 'Assessment: Chest pain, likely cardiac.',
        after: 'Assessment: Acute chest pain syndrome with features suggestive of unstable angina. Differential includes NSTEMI, aortic dissection, and pulmonary embolism. Risk stratification indicates intermediate probability for ACS.'
      }
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Generation Mode (Python) theme={null}
  import requests

  url = "https://api.sully.ai/alpha/note-templates"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "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."
  }

  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  print(result)
  ```

  ```python Refinement Mode (Python) theme={null}
  import requests

  url = "https://api.sully.ai/alpha/note-templates"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "mode": "refine",
      "template": {
          "id": "existing-template-123",
          "title": "Cardiology Consultation Template",
          "sections": [
              # ... existing template sections
          ]
      },
      "instructions": "Add more detailed assessment prompts and include differential diagnosis section",
      "note_comparison": {
          "before": "Assessment: Chest pain, likely cardiac.",
          "after": "Assessment: Acute chest pain syndrome with features suggestive of unstable angina. Differential includes NSTEMI, aortic dissection, and pulmonary embolism. Risk stratification indicates intermediate probability for ACS."
      }
  }

  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  print(result)
  ```
</RequestExample>

<ResponseExample>
  ```json Generation Job - 202 Accepted theme={null}
  {
    "data": {
      "id": "template_abc123def456",
      "mode": "generate",
      "status": "pending",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  }
  ```

  ```json Refinement Job - 202 Accepted theme={null}
  {
    "data": {
      "id": "template_xyz789ghi012",
      "mode": "refine",
      "status": "pending",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  }
  ```
</ResponseExample>

## Status Codes

<ResponseField name="202" type="Accepted">
  Note template job created successfully and is being processed
</ResponseField>

<ResponseField name="400" type="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
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Invalid or missing API key
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Server error occurred while processing the request
</ResponseField>

## Validation Rules

<Warning>
  **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
</Warning>

## Next Steps

After creating a note template job:

1. **Poll for results**: Use the [Get Note Template](/api-reference-alpha/note-templates/get) 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](/api-reference-alpha/note-templates/delete) 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

```json Generation Mode theme={null}
{
  "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."
}
```

```json Refinement Mode theme={null}
{
  "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."
}
```

## Related Endpoints

* [Get Note Template](/api-reference-alpha/note-templates/get) - Retrieve a template job and results
* [Delete Note Template](/api-reference-alpha/note-templates/delete) - Delete a template job