SOAP Note API

The SOAP Note API is designed to transform shorthand notes into structured SOAP Notes, making it an essential tool for healthcare providers such as Nurse Practitioners, Physicians, and Physical Therapists. This transformation facilitates efficient documentation and standardization of patient encounters in medical records.

The SOAP Note model

The SOAP Note model contains four main sections: Subjective, Objective, Assessment, and Plan. Each section captures different aspects of a patient encounter.

Properties

  • Name
    Subjective
    Type
    object
    Description

    Captures the patient's statement and history as described by them.

  • Name
    Objective
    Type
    object
    Description

    Records objective, measurable data collected during the patient's visit.

  • Name
    Assessment
    Type
    object
    Description

    Represents the healthcare provider's diagnosis and evaluation.

  • Name
    Plan
    Type
    object
    Description

    Details the treatment plan, including medications, therapies, and follow-up information.


Authentication

To access the API, you need to include an API key in the Authorization header of every request.

Obtaining an API Key

Email support@soapnoteai.com to request an API key.

Using the API Key

Include the API key in each request to the API by adding it to the Authorization header as follows:

Authorization: Bearer YOUR_API_KEY_HERE

POST/v1/note

Generate SOAP Note

This endpoint allows you to generate a structured SOAP Note from the provided shorthand clinical notes.

Required attributes

  • Name
    shorthand_notes
    Type
    string
    Description

    The shorthand clinical notes to be transformed into a SOAP Note.

  • Name
    provider_type
    Type
    string
    Description

    The type of healthcare provider. Can be "nurse_practitioner" or "physician".

Request

POST
/v1/note
curl -X POST https://prod.soapnoteapi.com/v1/note \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "shorthand_notes": "CC: 48M, persistent dry cough + SOB x 2 weeks. HPI: Cough ↑ at night, SOB w/ minimal exertion. Wheezing occasionally. No fever, but night sweats. No travel/sick contacts. PMH: HTN (5 yrs) on lisinopril. Ex-smoker (quit 10 yrs). No allergies. Meds: Lisinopril 10mg daily. OTC cough meds, limited relief. Social: Lives w/ wife, 2 kids. Bank manager. Social drinker. No drugs. Family: Father: MI at 65. Mother: Type 2 diabetes. Sister: Asthma. ROS: No GI issues/weight change/appetite change. Occasional headaches, no vision/dizziness issues.",
    "provider_type": "nurse_practitioner"
  }'

Response

{
  "noteId": "unique-note-identifier",
  "Subjective": {
    "Chief Complaint": "The patient is a 48-year-old male presenting with a persistent dry cough and shortness of breath for the past two weeks.",
    "History of Present Illness": "The patient reports that his cough worsens at night and experiences shortness of breath with minimal exertion. He occasionally experiences wheezing. He denies having a fever but has been experiencing night sweats. He has not recently traveled or been in contact with anyone sick.",
    "Past Medical History": "The patient has a history of hypertension for the past five years and is currently on Lisinopril. He is an ex-smoker, having quit 10 years ago, and has no known allergies.",
    "Medications": "The patient is taking Lisinopril 10mg daily and over-the-counter cough medications, which provide limited relief.",
    "Social History": "The patient lives with his wife and two children. He works as a bank manager. He is a social drinker and denies any illicit drug use.",
    "Family History": "The patient's father had a myocardial infarction at the age of 65. His mother has type 2 diabetes, and his sister has asthma.",
    "Review of Systems": "The patient denies any gastrointestinal issues, weight changes, or changes in appetite. He occasionally experiences headaches but denies any vision problems or dizziness."
  },
  "Objective": {
    "Vital Signs": "Not Available",
    "Physical Examination": "Not Available",
    "Diagnostic Test Results": "Not Available",
    "Specialized Examinations": "Not Available",
    "Height and Weight": "Not Available",
    "Skin": "Not Available",
    "Wound or Incision Assessment": "Not Available",
    "General Appearance": "Not Available"
  },
  "Assessment": {
    "Clinical Impression": "Given the patient's history of hypertension, persistent dry cough, and shortness of breath, a respiratory condition such as chronic obstructive pulmonary disease (COPD) or asthma could be considered. However, further diagnostic tests are needed to confirm.",
    "Diagnosis": "Not Available",
    "Analysis of Findings": "Not Available",
    "Severity and Complexity": "Not Available",
    "Response to Interventions": "Not Available",
    "Problem List": "Not Available",
    "Multidisciplinary Considerations": "Not Available"
  },
  "Plan": {
    "Diagnostic Studies": "Further diagnostic tests are needed to confirm the suspected respiratory condition.",
    "Therapeutic Interventions": "Not Available",
    "Patient Education and Counseling": "The patient should be educated on the importance of monitoring his symptoms and seeking immediate medical attention if they worsen.",
    "Referrals and Consultations": "A referral to a pulmonologist may be necessary depending on the results of the diagnostic tests.",
    "Self-Care and Lifestyle Modifications": "The patient should continue to avoid smoking and limit alcohol consumption.",
    "Collaboration and Coordination": "Not Available",
    "Emergency or Contingency Plans": "Not Available"
  }
}

POST/v1/stream/note

Stream SOAP Note

This endpoint allows you to stream the generated SOAP Note back to the client in real-time, allowing the client to parse the response progressively.

Required attributes

  • Name
    shorthand_notes
    Type
    string
    Description

    The shorthand clinical notes to be transformed into a SOAP Note.

  • Name
    provider_type
    Type
    string
    Description

    The type of healthcare provider. Can be "nurse_practitioner" or "physician".

Request

POST
/v1/stream/note
curl -X POST https://prod.soapnoteapi.com/v1/stream/note \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "shorthand_notes": "CC: 48M, persistent dry cough + SOB x 2 weeks. HPI: Cough ↑ at night, SOB w/ minimal exertion. Wheezing occasionally. No fever, but night sweats. No travel/sick contacts. PMH: HTN (5 yrs) on lisinopril. Ex-smoker (quit 10 yrs). No allergies. Meds: Lisinopril 10mg daily. OTC cough meds, limited relief. Social: Lives w/ wife, 2 kids. Bank manager. Social drinker. No drugs. Family: Father: MI at 65. Mother: Type 2 diabetes. Sister: Asthma. ROS: No GI issues/weight change/appetite change. Occasional headaches, no vision/dizziness issues.",
    "provider_type": "nurse_practitioner"
  }'

Response

// The response will be streamed in real-time.
// The client must handle the streamed data appropriately.

Error Handling

When an error occurs, the API will return a JSON response with the following structure:

{
  "error": "ErrorCode",
  "message": "Description of the error."
}

The SOAP Note API supports various healthcare provider types, each with a specialized system prompt tailored to their specific field of practice. This ensures that the generated SOAP Notes are relevant and accurate for each provider type.

Supported Provider Types

The following provider types are currently supported by the SOAP Note API:

  • Name
    nurse_practitioner
    Type
    string
    Description

    Advanced practice registered nurses who provide a wide range of healthcare services.

  • Name
    physician
    Type
    string
    Description

    Medical doctors who diagnose and treat illnesses, injuries, and other health conditions.

  • Name
    dentist
    Type
    string
    Description

    Healthcare professionals specializing in oral health and dental care.

  • Name
    psychotherapist
    Type
    string
    Description

    Mental health professionals who provide therapy for various psychological issues.

  • Name
    physical_therapy
    Type
    string
    Description

    Specialists in physical rehabilitation and movement disorders.

  • Name
    social_worker
    Type
    string
    Description

    Professionals who help individuals, families, and communities improve their well-being.

  • Name
    speech_language_pathology
    Type
    string
    Description

    Experts in communication disorders and swallowing difficulties.

  • Name
    psychiatrist
    Type
    string
    Description

    Medical doctors specializing in mental health and psychiatric disorders.

  • Name
    occupational_therapy
    Type
    string
    Description

    Therapists who help patients develop, recover, and improve skills for daily living.

  • Name
    chiropractor
    Type
    string
    Description

    Healthcare professionals focusing on disorders of the musculoskeletal system.

  • Name
    registered_nurse
    Type
    string
    Description

    Licensed nurses who provide and coordinate patient care.

  • Name
    veterinary
    Type
    string
    Description

    Medical professionals who treat diseases and injuries in animals.

  • Name
    massage_therapy
    Type
    string
    Description

    Practitioners who manipulate soft tissues for therapeutic purposes.

  • Name
    pharmacy
    Type
    string
    Description

    Healthcare professionals specializing in the preparation and dispensing of medications.

  • Name
    podiatrist
    Type
    string
    Description

    Medical specialists focused on foot, ankle, and lower extremity disorders.

  • Name
    acupuncture
    Type
    string
    Description

    Practitioners of traditional Chinese medicine using needle insertion techniques.

  • Name
    dermatologist
    Type
    string
    Description

    Medical specialists focused on skin, hair, and nail disorders.

Common Errors

  • Name
    UNAUTHORIZED
    Type
    401
    Description

    Invalid API key provided. Please check your credentials and try again.

  • Name
    BAD_REQUEST
    Type
    400
    Description

    One or more parameters are missing or invalid. Please review the request and try again.

  • Name
    RATE_LIMIT_EXCEEDED
    Type
    429
    Description

    You have exceeded the rate limit for requests. Please wait before making additional requests.

  • Name
    INTERNAL_SERVER_ERROR
    Type
    500
    Description

    An unexpected error occurred on our server. We are working to resolve this issue.

  • Name
    SERVICE_UNAVAILABLE
    Type
    503
    Description

    The service is currently unavailable due to maintenance or high load. Please try again later.

Was this page helpful?