SOAPNoteAPI Documentation

Authorization: Bearer snapi_sk_live_••••••••••••••••

curl -X POST https://api.soapnoteapi.com/v1/note \
  -H "Authorization: Bearer snapi_sk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "transcript": "Patient presents with headaches since medication change...",
    "specialty":  "nurse_practitioner",
    "include_billing_codes":   true,
    "include_patient_summary": true,
    "context": {
      "patient_info": {
        "name":            "John Smith",
        "age":             45,
        "gender":          "male",
        "medications":     ["Lisinopril 10mg", "Metformin 500mg"],
        "allergies":       ["Penicillin"],
        "medical_history": "Type 2 diabetes, hypertension"
      },
      "patient_history": "Last visit 2 weeks ago: discussed medication
                          adjustment for blood pressure control...",
      "chat_messages": [
        {
          "role":      "patient",
          "content":   "I have been having headaches since the medication change",
          "timestamp": "2026-03-14T10:00:00Z"
        },
        {
          "role":      "provider",
          "content":   "How often and how severe?",
          "timestamp": "2026-03-14T10:01:00Z"
        }
      ]
    }
  }'

{
  "noteId":     "note_01jfg8h4kx9a3bc7d2ef",
  "subjective": "45-year-old male with history of Type 2 diabetes and
                 hypertension presents with new-onset headaches following
                 a recent medication adjustment...",
  "objective":  "Blood pressure 148/92. Heart rate 76. Alert and oriented.
                 No focal neurological deficits noted...",
  "assessment": "Medication-related headache in the setting of recent
                 antihypertensive adjustment. Possible inadequate BP control.",
  "plan":       "1. Hold Lisinopril dose increase — revert to prior dose.
                 2. Recheck BP in 72 hours.
                 3. Patient instructed to log daily headache severity.
                 4. Follow-up in 2 weeks.",
  "transcript": "Patient presents with headaches since medication change...",
  "billing_codes": {
    "icd10": [
      { "code": "G44.309", "description": "Post-traumatic headache, unspecified" },
      { "code": "I10",     "description": "Essential (primary) hypertension" }
    ],
    "cpt": [
      { "code": "99214", "description": "Office visit, established patient, moderate complexity" }
    ]
  },
  "billing_codes_disclaimer": "Recommended codes for review. Not a substitute
    for professional coding. Verify all codes before submission.",
  "patient_summary": "During your visit today, we discussed the headaches
    you have been experiencing since your blood pressure medication was
    adjusted. Based on the examination, we believe the headaches may be
    related to the medication change. We are reverting your Lisinopril
    to the previous dose and would like you to track your headaches daily.
    Please follow up with us in 2 weeks.",
  "expires_at": "2026-06-15T00:00:00Z"
}

curl -X POST https://api.soapnoteapi.com/v1/stream/note \
  -H "Authorization: Bearer snapi_sk_live_••••••••" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "transcript": "Patient presents with headaches since medication change...",
    "specialty": "nurse_practitioner"
  }'

data: {"section":"subjective","content":"42-year-old male with 3-week history of..."}

data: {"section":"objective","content":"Lumbar ROM restricted at 40° flexion..."}

data: {"section":"assessment","content":"Mechanical lower back pain, likely muscular..."}

data: {"section":"plan","content":"1. NSAIDs PRN. 2. Physical therapy referral..."}

data: [DONE]

"billing_codes": {
  "icd10": [
    { "code": "M54.50", "description": "Low back pain, unspecified",
      "requires_clinician_review": true }
  ],
  "cpt": [
    { "code": "99214", "description": "Office visit, established patient, moderate complexity",
      "mdm_level": "moderate", "requires_clinician_review": true }
  ],
  "hcpcs": [
    { "code": "G0283", "description": "Electrical stimulation, unattended",
      "requires_clinician_review": true }
  ],
  "icd11": [
    { "code": "ME84.2", "description": "Low back pain (ICD-11 — advisory, not for US claims)",
      "requires_clinician_review": true }
  ]
},
"billing_codes_disclaimer": "These codes and the medical decision-making (MDM)
  assessment are AI-generated decision support... A qualified clinician and/or
  professional coder must review and approve all codes before submission.
  ICD-11 codes, when included, are advisory only and are not accepted by US payers."

"patient_summary": "During your visit today, we discussed your ongoing
  lower back pain. The examination showed some tenderness in your lower
  back area. Based on the findings, this appears to be a muscle strain.
  The plan is to continue your current pain medication, try gentle
  stretching exercises, and schedule a follow-up in 4 weeks."

curl -X PUT https://api.soapnoteapi.com/v1/note/audio \
  -H "Authorization: Bearer snapi_sk_live_••••••••" \
  -F "audio=@/path/to/recording.mp3" \
  -F 'metadata={"specialty":"nurse_practitioner","template":"standard","include_transcript":true,"include_billing_codes":true,"include_icd11":true,"include_patient_summary":true}'

{
  "noteId":  "note_01jfg8h4kx9a3bc7d2ef",
  "status":  "processing",
  "message": "Audio accepted. Poll GET /v1/audio/status/:noteId for status."
}

"transcript_structured": [
  { "speaker": "PROVIDER", "text": "What brings you in today?",
    "start": 0.0, "end": 2.1, "speaker_inferred": true },
  { "speaker": "PATIENT", "text": "I've had a headache for three days.",
    "start": 2.4, "end": 5.0, "speaker_inferred": true }
],
"transcript_disclaimer": "This transcript is machine-generated and may contain
  transcription errors. Speaker labels (PROVIDER/PATIENT) are AI-inferred and
  may be incorrect. Review against the source audio before relying on it."

curl https://api.soapnoteapi.com/v1/note/note_01jfg8h4kx9a3bc7d2ef \
  -H "Authorization: Bearer snapi_sk_live_••••••••"

curl -X POST https://api.soapnoteapi.com/v1/visit-summary \
  -H "Authorization: Bearer snapi_sk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_info": {
      "name": "Jane Doe",
      "age":  62
    },
    "focus": "diabetes management",
    "visits": [
      {
        "visit_date": "2026-02-15",
        "provider":   "Dr. Smith",
        "soap_note": {
          "assessment": "E11.65 Type 2 DM with hyperglycemia",
          "plan":       "Increased Metformin to 1000mg BID. Recheck A1C in 3 months."
        }
      },
      {
        "visit_date": "2026-01-10",
        "provider":   "Dr. Smith",
        "summary":    "Routine follow-up. A1C 7.8%, up from 7.2%. Blood pressure well controlled."
      }
    ]
  }'

{
  "summary": "62-year-old patient with Type 2 diabetes showing upward A1C
    trend (7.2% -> 7.8%) over the past 2 months. Metformin was increased
    to 1000mg BID at the last visit. Blood pressure well controlled on
    current regimen. Key follow-up: recheck A1C and fasting glucose.",
  "key_findings": [
    "A1C trending upward: 7.2% -> 7.8%",
    "Metformin recently increased to 1000mg BID",
    "Blood pressure stable on current medications"
  ],
  "active_diagnoses": [
    { "code": "E11.65", "description": "Type 2 DM with hyperglycemia" }
  ]
}

{
  "error": {
    "code":    "invalid_api_key",
    "message": "The API key is missing or invalid.",
    "details": {}
  }
}