Search the OSCAR Documentation
< All Topics


Share this

Documentation Copyright © 2023 Adrian Starzynski. Some content from other creators see Credits


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 (

(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.


Read more about SOAP vs. REST

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

AuthenticationWS-SecurityOAuth 1.0a
Data FormatOnly XML.Plain text, HTML, XML, JSON, YAML, and others.
PerformanceLess reliable than REST and consumes more resourcesBetter performance and reliability compared to SOAP
ApproachFunction-driven (data available as services, e.g.: “getAllergy”)Data-driven (data available as resources, e.g. “user”).
StatefulnessStateless by default, but it’s possible to make a SOAP API stateful.Stateless (no server-side sessions).
CachingAPI calls cannot be cached.API calls can be cached.
OverallHigh 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.


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 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):
(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:

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 ( 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<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

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.


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:





/demographics/ POST/DELETE






-Patient Detail Status


/pharmacies (POST/PUT/DELETE)

-Product Dispensing





-RSS Feed




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


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)

Table of Contents