Skip to main content

​
Overview

Generate or regenerate a markdown doctor letter for a specific appointment in MediSync using AI-powered letter generation. This endpoint creates professional medical correspondence by analyzing appointment notes, patient data, and diagnosis information to produce formatted referral letters.
AI-Powered Letter Generation: This endpoint uses an external AI agent to generate professional doctor letters in markdown format based on appointment notes, patient information, diagnosis predictions, and provided recipient details.

​
Authentication

curl -X POST \
  'https://api.medisync.com/doctor-letters/generate/apt_abc123?uid=doc_xyz789' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipient_doctor": "Dr. Sarah Johnson, Cardiology Specialist",
    "referring_doctor": "Dr. Michael Chen, Internal Medicine",
    "language": "en"
  }'

​
Path Parameters

​
appointment_id
string
required
The appointment ID to generate the doctor letter for

​
Query Parameters

​
uid
string
required
The doctor ID (user ID) of the healthcare provider generating the letter

​
Body Parameters

​
recipient_doctor
string
The name and title of the doctor or specialist receiving the letter
​
referring_doctor
string
The name and title of the doctor making the referral
​
language
string
Language code for letter generation (e.g., “en”, “de”, “es”). If not provided, uses the appointment’s language setting or defaults to “de”.

​
Response

​
success
boolean
Indicates if the operation was successful
​
data
object
The generated or updated doctor letter object
​
error
string
Error message if the operation failed

​
Example Response

{
  "success": true,
  "data": {
    "_id": "letter_def456",
    "appointment_id": "apt_abc123",
    "patient_id": "pat_ghi789",
    "doctor_id": "doc_xyz789",
    "status": "generated",
    "markdown_content": "# Medical Referral Letter\n\n**Date:** 2024-01-15\n\n**To:** Dr. Sarah Johnson, Cardiology Specialist\n**From:** Dr. Michael Chen, Internal Medicine\n\n**Re:** John Smith (DOB: 1975-08-15)\n\n## Clinical Summary\n\nI am referring Mr. Smith for cardiology evaluation following his recent presentation with chest pain...\n\n## Diagnosis\n- Atypical chest pain (ICD-10: R07.89)\n\n## Current Medications\n- Lisinopril 20mg daily\n\n## Recommendation\nPlease evaluate for possible cardiac etiology and provide treatment recommendations.\n\nThank you for your consultation.\n\nDr. Michael Chen, MD",
    "generation_inputs": {
      "current_date": "2024-01-15",
      "patient_name": "John Smith",
      "date_of_birth": "1975-08-15",
      "appointment_notes": "Patient presented with chest pain...",
      "diagnosis": "Atypical chest pain",
      "icd_10_codes": ["R07.89"],
      "recipient_doctor": "Dr. Sarah Johnson, Cardiology Specialist",
      "referring_doctor": "Dr. Michael Chen, Internal Medicine",
      "language": "en"
    },
    "error": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:32:00.000Z"
  }
}

​
Generation Process

  1. Data Validation: Validates appointment exists and retrieves associated notes and patient data
  2. Input Preparation: Assembles patient information, notes, diagnosis, and request parameters
  3. AI Session: Establishes session with external AI agent for letter generation
  4. Content Generation: Sends structured prompt to AI agent for markdown letter creation
  5. Post-Processing: Cleans up generated content (removes code fences, formats)
  6. Database Storage: Saves generated letter with all metadata and inputs

​
Behavior Notes

  • Create or Update: If a doctor letter already exists for the appointment and doctor, it will be updated. Otherwise, a new letter is created.
  • Status Tracking: The letter status progresses from “pending” → “generated” (success) or “failed” (error)
  • AI-Generated Content: Uses external RAGFlow AI agent to generate professional medical correspondence
  • Input Storage: All generation inputs are stored for reference and potential regeneration
  • Markdown Format: Generated content is in markdown format for flexible rendering and editing
  • Language Support: Supports multiple languages with fallback to appointment or default language

​
Status Codes

  • 200 - Letter generated successfully
  • 400 - Invalid request data or generation error
  • 404 - Appointment, notes, or patient not found
  • 500 - AI service error or database failure