Getting Started

Generate Your First SOAP Note

Go from zero to a structured SOAP note in under 5 minutes using cURL, JavaScript, or Python.

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.

Prerequisites

A SOAPNoteAPI account. Sign up for free at app.soapnoteapi.com/signup.
An API key. Create one from the dashboard. Test keys (snapi_sk_test_...) include 10 free requests per day.
An HTTP client: cURL, Node.js with fetch, Python with requests, or any language that can make HTTP POST requests.

Make your first request

The minimum request requires two fields: transcript (the clinical text to convert) and specialty (the medical specialty for formatting). Send them as JSON to POST /v1/note.

cURL

Terminal

curl -X POST https://api.soapnoteapi.com/v1/note \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transcript": "Patient is a 38-year-old female presenting for follow-up of hypertension. She reports compliance with lisinopril 10mg daily. Denies headaches, chest pain, or shortness of breath. Blood pressure today is 128/82. Heart rate 72. Lungs clear bilaterally. No peripheral edema. Assessment: hypertension, well controlled on current medication. Plan: continue lisinopril 10mg daily, recheck blood pressure in 3 months, reinforce low-sodium diet.",
    "specialty": "nurse_practitioner"
  }'

JavaScript (fetch)

JavaScript

const response = await fetch("https://api.soapnoteapi.com/v1/note", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    transcript: "Patient is a 38-year-old female presenting for follow-up of hypertension. She reports compliance with lisinopril 10mg daily. Denies headaches, chest pain, or shortness of breath. Blood pressure today is 128/82. Heart rate 72. Lungs clear bilaterally. No peripheral edema. Assessment: hypertension, well controlled on current medication. Plan: continue lisinopril 10mg daily, recheck blood pressure in 3 months, reinforce low-sodium diet.",
    specialty: "nurse_practitioner",
  }),
});

const note = await response.json();
console.log(note);

Python (requests)

Python

import requests

response = requests.post(
    "https://api.soapnoteapi.com/v1/note",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "transcript": "Patient is a 38-year-old female presenting for follow-up of hypertension. She reports compliance with lisinopril 10mg daily. Denies headaches, chest pain, or shortness of breath. Blood pressure today is 128/82. Heart rate 72. Lungs clear bilaterally. No peripheral edema. Assessment: hypertension, well controlled on current medication. Plan: continue lisinopril 10mg daily, recheck blood pressure in 3 months, reinforce low-sodium diet.",
        "specialty": "nurse_practitioner",
    },
)

note = response.json()
print(note)

Read the response

A successful response contains the four SOAP sections -- subjective, objective, assessment, and plan -- along with a noteId you can use to retrieve the note later, and an expires_at timestamp indicating when the note will be automatically deleted from SOAPNoteAPI servers.

JSON

{
  "noteId": "note_01jfg8h4kx9a3bc7d2ef",
  "subjective": "38-year-old female presents for follow-up of essential hypertension. Patient reports good compliance with lisinopril 10mg daily. Denies headaches, chest pain, dizziness, or shortness of breath. No new symptoms or medication side effects reported.",
  "objective": "Vital Signs: BP 128/82 mmHg, HR 72 bpm. Cardiovascular: Regular rate and rhythm, no murmurs. Lungs: Clear to auscultation bilaterally. Extremities: No peripheral edema noted.",
  "assessment": "Essential hypertension (I10), well controlled on current antihypertensive regimen. Blood pressure at goal on lisinopril 10mg daily.",
  "plan": "1. Continue lisinopril 10mg PO daily.\n2. Reinforce dietary modifications including low-sodium diet.\n3. Recheck blood pressure in 3 months.\n4. Routine labs (BMP, lipid panel) at next visit.",
  "transcript": "Patient is a 38-year-old female presenting for follow-up of hypertension...",
  "expires_at": "2026-06-18T00:00:00Z"
}

Warning: Data retention: Notes are automatically deleted after the expires_at date. If you need to keep the note, store it in your own system after generation.

Retrieve a note by ID

Use the noteId from the generation response to fetch the note again with GET /v1/note/:noteId. This is useful for polling after async audio uploads or retrieving a note within its retention window.

cURL

Terminal

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

JavaScript (fetch)

JavaScript

const response = await fetch(
  "https://api.soapnoteapi.com/v1/note/note_01jfg8h4kx9a3bc7d2ef",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
    },
  }
);

const note = await response.json();
console.log(note);

Python (requests)

Python

import requests

response = requests.get(
    "https://api.soapnoteapi.com/v1/note/note_01jfg8h4kx9a3bc7d2ef",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)

note = response.json()
print(note)

The response includes a status field. For text-based notes, the status is always "completed". For audio-based notes, it may be "processing", "completed", or "failed".

Next steps

Audio Upload -- Generate SOAP notes directly from audio recordings without building your own transcription pipeline.
Specialties and Templates -- Choose the right specialty and template for accurate, specialty-specific note formatting.
Streaming -- Stream notes in real time with Server-Sent Events for a responsive provider experience.
API Reference -- Full endpoint reference with all request and response fields at /docs.

Authentication and API Keys

Need help? Contact support@soapnoteapi.com