OSCAR’s API
Documentation Copyright © 2023 Adrian Starzynski. Some content from other creators see Credits
Introduction
OSCAR supports REST and SOAP connections. However, you’ll need to use REST for performing some operations that require a higher security level. Also, it is recommended to only use the REST integration, because most OSCAR systems now have MFA/2FA and a requirement for PIN, meaning SOAP won’t work (since SOAP needs a login only with username/password and no PIN, and MFA also requires a unique code/push notification to be accepted, which won’t work with SOAP). REST also provides access to more web services and requires the app to be authenticated in OSCAR first via OAUTH.
OSCAR exposes it’s web services to authorized users only. Apps must be registered on the OSCAR it would like to integrate with and it’s not the app that “logs in”, it’s the provider. The provider will login directly into OSCAR, which will generate a token for the app to make further calls.
The protocol implemented in OAUTH 1.0a (https://oauth.net/core/1.0a/)
(OSCAR uses OAUTH 1.0a for REST authentication)
When setting up the OAUTH you may experience challenges around how the payload is encrypted. I believe it only works to use plaintext, or one of the various options.
REST and SOAP APIs
APIs provide various endpoints to access clinical data in JSON and XML formats. Although it’s a matter of personal preference, in general, REST services are the recommended approach for the sake of simplicity, performance and scalability. The table below summarizes some of the key differences between the REST and SOAP APIs
SOAP | REST | |
---|---|---|
Authentication | WS-Security | OAuth 1.0a |
Data Format | Only XML. | Plain text, HTML, XML, JSON, YAML, and others. |
Performance | Less reliable than REST and consumes more resources | Better performance and reliability compared to SOAP |
Approach | Function-driven (data available as services, e.g.: “getAllergy”) | Data-driven (data available as resources, e.g. “user”). |
Statefulness | Stateless by default, but it’s possible to make a SOAP API stateful. | Stateless (no server-side sessions). |
Caching | API calls cannot be cached. | API calls can be cached. |
Overall | High security, standardized, lower performance, more complexity, less flexibility. | Scalability, better performance, browser-friendliness, flexibility. |
REST API Reference
The full OSCAR EMR REST API reference is available here.
Configuration
To configure your application to work with OSCAR via REST API, follow the steps1:
1. Enable the REST API in OSCAR for connecting apps. In the oscar.properties file of the OSCAR system, find the line “ModuleNames=” and add REST to it. If it does not exist simply add like below (or just uncomment the line if it exists commented):
ModuleNames=REST
(then restart Tomcat)
2. Register the app with OSCAR through the Administration interface.
Go to Administration>Integration>REST Clients

3. Click “Add New“
Enter a valid URI for the application (must be the base URL of your web application), and a Token Lifetime. You can enter a Token Lifetime of -1 if the token shouldn’t expire (this is the most common setting for integrations).

4. Use the Client Key and Client Secret in your app’s OAUTH initialization.
Sample OAUTH 1.0a Workflow1
1. Client makes a REST call including proper “Authorization” header. (for example: https://example.com/oscar/ws/services/providerService/providers_json)
2. OSCAR will either return the results of the call (regular 200 HTTP status) or a 401 requiring the user to authorize with OSCAR first. Assuming we get the 401,
3. Client will initiate the OAUTH 1.0a flow by calling initiate (https://example.com/oscar/ws/oauth/initiate). Make sure the client properly manages any cookies as well. This call will also include the callback URL to your application. This will get called when the OAUTH workflow is completed. This will return you a Request Token.
4. Client now redirects user to https://example.com/oscar/ws/oauth/authorize?oauth_token=<request_token>.
5. User authorizes with OSCAR

4. User is redirected to the Callback URL of your application (specified in the initiate, and must be within the URI of the registered application). The URL will have parameters for the oauth_token and oauth_verifier.
5. Client requests an access token from https://example.com/oscar/ws/oauth/token
6) Client makes REST calls using Authorization header with access token.
Full List of Web Services
Whether you’re developing a SOAP or REST integration with OSCAR, you can go to your OSCAR server URL /ws to see the WSDL and WADL files for all the services offered on that particular OSCAR version. OSCAR vendors have added their own additional features/fixes to their version’s API.
Example: https://example.com/oscar/ws
For a zip file with the example WADL files of the RESTful services click here
Click the above link to get the WADL files that describe the REST services available on most OSCAR versions. Some vendors have added additional functionality/endpoints (check your OSCAR system’s /oscar/ws link for the exact specifications for your version).
REST Services
OSCAR offers a multitude of RESTful web services.
Here is the standard list of RESTful web services that are available in 99% of all OSCAR systems:
-App
/app/getApps
-Billing
/billing/uniqueServiceTypes
/billing/billingRegion
-Consultation
/consults/searchRequests
/consults/getRequest
/consults/getRequestAttachments
/consults/saveRequest
/consults/searchResponses
/consults/getResponse
/consults/getResponseAttachments
/consults/saveResponse
-DemographicMerge
/demographics/merge
-Demographic
/demographics
/demographics/{id}
/demographics/ POST/DELETE
/demographics/quickSearch
/demographics/search
/demographics/searchIntegrator
-Forms
/forms/{demo}/all
/forms/allEForms
/forms/selectedEncounterForms
/forms/{demo}/completedEncounterForms
/forms/groupNames
/forms/getK2AEForm
-Inbox
/inbox/mine
-Messaging
/messaging/unread
/messaging/count
-Notes
/notes/{demo}/all
/notes/{demo}/tmpSave
/notes/{demo}/save
/notes/{demo}/saveIssueNote
/notes/{demo}/getCurrentNote
/notes/getIssueNote/{noteId}
/notes/getGroupNoteExt/{noteId}
/notes/getIssueId/{issueCode}
/notes/ticklerGetNote/{ticklerNo}
/notes/ticklerSaveNote
-OscarJob
/jobs/type/current
/jobs/types/all
/jobs/all
/jobs/{jobId}
/jobs/saveJob
/jobs/cancelJob
/jobs/saveCrontabExpression
/jobs/saveJobType
/jobs/enableJob
/jobs/disableJob
-Patient Detail Status
/patientDetailStatusService/getStatus
patientDetailStatusService/validateHC
-Persona
/persona/rights
/persona/hasRight
/persona/hasRights
/persona/navbar
/persona/setDefaultProgramInDomain
/persona/patientLists
/persona/preferences
/persona/updatePreferences
-Pharmacy
/pharmacies
/pharmacies/{pharmId}
/pharmacies (POST/PUT/DELETE)
-Product Dispensing
/productDispensing/saveDrugProduct
/productDispensing/drugProduct/{id}
/productDispensing/drugProducts
/productDispensing/drugProductsByCode
/productDispensing/drugProducts/uniqueNames
/productDispensing/drugProducts/uniqueLots
/productDispensing/deleteDrugProduct/{id}
/productDispensing/productLocations
/productDispensing/status/{drugId}
/productDispensing/drugProductTemplates
-Program
/program/patientList
/program/programList
-Provider
/providerService/providers
/providerService/provider/{id}
/providerService/provider/me
/providerService/providers/search
/providerService/getRecentDemographicsViewed
/providerService/getActiveTeams
/providerService/settings/get
/providerService/settings/{providerNo}/save
-RecordUX
/recordUX/{demo}/recordMenu
/recordUX/{demo}/summary/{summaryName}
/recordUX/{demo}/getFamilyHistory
/recordUX/{demo}/getMedicalHistory
/recordUX/{demo}/getOngoingConcerns
/recordUX/{demo}/getOtherMeds
/recordUX/{demo}/getReminders
-Reporting
/reporting/demographicSets/list
/reporting/demographicSets/demographicSet/{name}
/reporting/demographicSets/patientList
/reporting/eformReportTool/list
/reporting/eformReportTool/add
/reporting/eformReportTool/populate
/reporting/eformReportTool/remove
/reporting/eformReportTool/markLatest
-RSS Feed
/rssproxy/rss
-Schedule
/schedule/day/{date}
/schedule/statuses
/schedule/add
/schedule/getAppointment
/schedule/deleteAppointment
/schedule/updateAppointment
/schedule/{demo}/appointmentHistory
/schedule/appointment/{id}/updateStatus
/schedule/appointment/{id}/updateType
/schedule/appointment/{id}/updateUrgency
/schedule/fetchMonthly/{providerNo}/{year}/{month}
/schedule/types
-Status
/status/checkIfAuthed
-Tickler
/tickler/search
/tickler/mine
/tickler/ticklers
/tickler/complete
/tickler/delete
/tickler/update
/tickler/textSuggestions
/tickler/add
SOAP Services
This page lists all the available SOAP services in OSCAR
OSCAR Source Code REST Java Files
For those who wish to review OSCAR’s Java source code files for the REST endpoints:
oscaremr / oscar / src / main / java / org / oscarehr / ws / rest — Bitbucket
Credits
1. Part of the REST configuration and Sample OAUTH Workflow is from Marc Dumontier’s original article “Connecting to OSCAR’s REST API” (publish date unknown)