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
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
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"
}
}
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
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.