SHP Patient Access API
home
Sharp Health Plan Patient API
V1.2 – June 10, 2021
This asset provides the API specification for the Patient Access API needed to meet CMS interoperability requirements and is built according to the below Implementation guides:
- Clinical Data: US Core FHIR R4 Implementation Guide 3.1.1, FHIR Version 4.0.1.
- Claims & Encounter Data: HL7 FHIR Consumer Directed PDex (CARIN IG for Blue Button®) IG: Version STU 1.0.0.
- Plan Coverage and Formularies: Da Vinci - PDex US Drug Formulary IG: Version STU 1.0.1.
OVERVIEW
Below are the high-level requirements per CMS rule for Patient Access API:
- Payers are required to make a patient’s clinical data, defined as those data the payer maintains that are included in the USCDI version 1, available via the Patient Access API.
- Payers are required to make a patient’s claims and encounter data available via the Patient Access API.
- Part D Medicare Advantage plans must make formulary information available via the Patient Access API.
To satisfy the clinical data requirement, the US Core 3.1.1 FHIR IG has been used. The Implementation Guide is based on _FHIR Version R4 _and defines the minimum conformance requirements for accessing patient data. To satisfy the claims & encounter data requirement, we adopted the CARIN STU 1.0.0 Implementation guide. The Da Vinci - PDex US Drug Formulary IG has been used for Medicare Part D formulary data requirement. All of these are read-only RESTful GET API calls (PUT and POST are not currently supported), allowing approved applications to access network patient information.
This API allows you to help SHP providers/customers by making information about patients easily accessible. It encourages consistency around how data access is accomplished between healthcare systems within and across organizations. This API also encourages consistency around what data is accessed and consistency around security standards.
By utilizing an approved Patient Access API applications, providers and customers are enabled to do the following:
- Use search parameters to filter practitioners by specialty, role and/or location
- Use search parameters to filter patient data by name, ID, address, gender
- Lookup patient medications, immunizations, diagnostic reports, conditions
- Find patients by type of observation (smoking status, vital signs, lab results, BMI for Age, height and weight)
- Lookup patients by location, encounter or procedures during hospitalization
- Retrieve patient’s claims & encounter data
- Retrieve drug formulary details
Capability Statement:
https://shp-apis.sharphealthplan.com/patientaccess/metadata
https://shp-apis.sharphealthplan.com/patientaccess/.well-known/smart-configuration
Use Case
The Centers for Medicare and Medicaid Services (CMS) finalized on May 1st, 2020, its Interoperability and Patient Access Final Rule on patient access to health data. This new rule aims to give payers an easy way to gain health information to patients/providers, along with strong security and privacy measures.
Patient/Payer Focused
The rule enables patients to have better access to their health information, improves interoperability, and drives innovation, while reducing the burden on payers and providers.
Basic Information Exchange
Patients can now be aware of their health information for better care and improved patient outcomes. With data being available conveniently and securely among payers, providers, and patients, CMS hopes to achieve real coordinated care, improved health outcomes, and reduced costs.
Security
SHP API requests often make use of patient-specific information which could be exploited by malicious actors resulting in exposure of patient data. For this reason, all SHP consumer access/patient transactions must be secured appropriately, and directed by regulations, with access limited to authorized individuals, data protected in transit, and appropriate audit measures taken. Authentication and authorization will occur during the process of granting access to patient data in accordance with SMART App Launch Framework and OpenID Connect. For details please refer to the OAuth & OpenID Connect Documentation on this portal.
Developers of third-party applications SHOULD be aware of these security considerations associated with FHIR transactions, particularly those related to:
- Communications
- Authentication
- Authorization/Access Control
- Audit Logging
- Digital Signatures
- Security Labels
- Narrative
Base URL
https://shp-apis.sharphealthplan.com/patientaccess
Resources
US CORE Patient Endpoints
Below are the details of the US Core profiles with their respective search parameters:
| Resource | Definition | Search Parameters | Examples/Combinations |
|---|---|---|---|
| AllergyIntolerance | A record of allergies/adverse reactions associated with a patient. | Query parameters: patient, clinical-status, id URI: id |
GET [base]/AllergyIntolerance?patient=[MRN] GET [base]/AllergyIntolerance/[id] GET [base]/AllergyIntolerance?patient=[MRN] |
| CarePlan | An assessment and plan of treatment data associated with a patient. | Query parameters: patient, category, date, status URI: id |
GET [base]/CarePlan?patient=[MRN]&category=[category] GET [base]/CarePlan/[id] GET [base]/CarePlan?patient=[MRN]&category=[category]&date=[YYYYMMDD] GET [base]/CarePlan?patient=[MRN]&category=[category]&date=[YYYYMMDD]&status=[status] |
| CareTeam | A resource identifying the Care Team members associated with a patient | Query parameters: patient, status URI: id |
GET [base]/CareTeam?patient=[MRN]&status=[status] GET [base]/CareTeam/[id] |
| Condition | A clinical condition, problem, diagnosis, or other event, situation, issue, or clinical concept that has risen to a level of concern. | Query parameters: patient, id, code, category, clinical-status URI: id |
GET [base]/Condition?patient=[MRN] GET [base]/Condition/[id] GET [base]/Condition?patient=[MRN]&code=[ICD-10] |
| DiagnosticReport (Report and Note, Laboratory Results) | The findings and interpretation of diagnostic tests performed on patients, groups of patients, devices, and locations, and/or specimens derived from these. The report includes clinical context such as requesting and provider information, and some mix of atomic results, images, textual and coded interpretations, and formatted representation of diagnostic reports. | Query parameters: patient, id,code, date URI: id |
GET [base]/DiagnosticReport?patient=[MRN] GET [base]/DiagnosticReport/[id] GET [base]/DiagnosticReport?patient=[MRN]&code=[LOINC] GET [base]/DiagnosticReport?patient=[MRN]&code=[LOINC]&date=[YYYYMMDD] |
| DocumentReference | This profile sets minimum expectations for searching and fetching patient documents including Clinical Notes using the DocumentReference resource. | Query parameters: patient, _id, category, type, status, date, period URI: id |
GET [base]/DocumentReference/[id] GET [base]/DocumentReference?_id=[document_id] GET [base]/DocumentReference?patient=[MRN] GET [base]/DocumentReference?patient=[MRN]&category=[category] GET [base]/DocumentReference?patient=[MRN]&category=[category]&date=[YYYYMMDD] GET [base]/DocumentReference?patient=[MRN]&type=[type] GET [base]/DocumentReference?patient=[MRN]&status=[status] |
| Encounter | An interaction between a patient and healthcare provider(s) for the purpose of providing healthcare service(s) or assessing the health status of a patient. | Query parameters: identifier, _id, patient, class, type, date URI: id |
GET [base]/Encounter?patient=[MRN] GET [base]/Encounter?identifier=[claim_id] GET [base]/Encounter?_id=[claim_id] GET [base]/Encounter/[id] GET [base]/Encounter?patient=[MRN]&date=[YYYYMMDD] GET [base]/Encounter?patient=[MRN]&class=[actCode] GET [base]/Encounter?patient=[MRN]&type=[SNOMED] |
| Goal | Describes the intended objective(s) for a patient, group or organization care, for example, weight loss, restoring an activity of daily living, obtaining herd immunity via immunization, meeting a process improvement objective, etc. | Query parameters: patient, target-date, lifecycle-status URI: id |
GET [base]/Goal/[id] GET [base]/Goal?patient=[MRN]&lifecycle-status=[code] GET [base]/Goal?patient=[MRN]&target-date=[YYYYMMDD] |
| Immunization | Describes the event of a patient being administered a vaccine or a record of an immunization as reported by a patient, a clinician or another party. | Query parameters: patient, subject, id, date, status URI: id |
GET [base]/Immunization?patient=[MRN] GET [base]/Immunization/[id] GET [base]/Immunization?patient=[MRN]&date=[YYYYMMDD] GET [base]/Immunization?patient=[MRN]&status=[status] |
| Location | Details and position information for a physical place where services are provided and resources and participants may be stored, found, contained, or accommodated. | Query parameters: name, address, address-city, address-state, address-postalcode, id URI: id |
GET [base]/Location?name=[string] GET [base]/Location?address=[string] GET [base]/Location?address-city=[string] GET [base]/Location?address-state=[string] GET [base]/Location?address-postalcode=[string] GET [base]/Location?name=[string]&address-city=[string] GET [base]/Location/[id] |
| MedicationRequest | An order or request for both supply of the medication and the instructions for administration of the medication to a patient. | Query parameters: patient, intent, status URI: id |
GET [base]/MedicationRequest/[id] GET [base]/MedicationRequest?patient=[MRN]&intent=[intent] GET [base]/MedicationRequest?patient=[MRN]&intent=[intent]&status=[status] |
| Observation (Smoking Status, Laboratory Results, Pediatric BMI, Pulse Oximetry, Pediatric Weight) | Measurements and simple assertions made about a patient, device or other subject. | Query parameters: patient, category, code, status, date URI: id |
GET [base]/Observation?patient=[MRN] GET [base]/Observation/[id] GET [base]/Observation?patient=[MRN]&code=[LOINC] GET [base]/Observation?patient=[MRN]&category=[category]&date=[YYYYMMDD] GET [base]/Observation?patient=[MRN]&date=[YYYYMMDD]&code=[LOINC] |
| Organization | A formally or informally recognized grouping of people or organizations formed for the purpose of achieving some form of collective action. Includes companies, institutions, corporations, departments, community groups, healthcare practice groups, payer/insurer, etc. | Query parameters: address, name URI: id |
GET [base]/Organization?name=[string] GET [base]/Organization?address=[string] GET [base]/Organization/[id] |
| Patient | Covers data about patients involved in a wide range of health-related activities | Query parameters: name, identifier, _id, birthDate, gender URI: id |
GET [base]/Patient/[id] GET [base]/Patient?_id=[MRN] GET [base]/Patient?identifier=[MRN] GET [base]/Patient?name=[string] GET [base]/Patient?name=[string]&birthdate=[YYYYMMDD] GET [base]/Patient?name=[string]&gender=[gender] |
| Practitioner | A person who is directly or indirectly involved in the provisioning of healthcare. | Query parameters: identifier, name, id URI: id |
GET [base]/Practitioner?name=[string] GET [base]/Practitioner?identifier=[NPI] GET [base]/Practitioner/[id] GET [base]/Practitioner/[NPI] |
| PractitionerRole | A specific set of Roles/Locations/specialties/services that a practitioner may perform at an organization for a period of time. | Query parameters: practitioner, specialty URI: id |
GET [base]/PractitionerRole?specialty=[specialty] GET [base]/PractitionerRole?practitioner=[NPI] GET [base]/PractitionerRole/[id] |
| Procedure | An action that is or was performed on or for a patient. This can be a physical intervention like an operation, or less invasive like long term services, counseling, or hypnotherapy. | Query parameters: patient, id, date, code, status URI: id |
GET [base]/Procedure?patient=[MRN] GET [base]/Procedure/[id] GET [base]/Procedure?patient=[MRN]&date=[YYYYMMDD] GET [base]/Procedure?patient=[MRN]&code=[SNOMED] GET [base]/Procedure?patient=[MRN]&code=[SNOMED]&date=[YYYYMMDD] GET [base]/Procedure?patient=[MRN]&code=0730,74176,99213&date=le20201029 |
CARIN Endpoints
Below are the details of the CARIN CPCDS Profiles with their respective search parameters:
| Resource | Definition | Search Parameters | Examples/Combinations |
|---|---|---|---|
| Coverage | Data that reflect a payer’s coverage that was effective as of the date of service or the date of admission of the claim. | Query parameters: subscriber, status, beneficiary, class-type, payor |
GET [base]/Coverage? subscriber=[subscriber] GET [base]/Coverage? status=[ status] GET [base]/Coverage? beneficiary=[ beneficiary] GET [base]/Coverage? class-type=[class-type] GET [base]/Coverage? payor=[payor] |
| Explanation of Benefit | This resource provides: the claim details; adjudication details from the processing of a Claim; and optionally account balance information, for informing the subscriber of the benefits provided.
It supports the CARIN BB Explanation of Benefit Profile, CARIN BB Explanation of Benefit Inpatient Institutional Profile, CARIN BB Explanation of Benefit Outpatient Institutional Profile, CARIN BB Explanation of Benefit Pharmacy Profile, and CARIN BB Explanation of Benefit Professional Non-Clinician Profile. |
Query parameters: _id, patient, type, identifier, service-date |
GET [base]/ExplanationOfBenefit?_id=[id] GET [base]/ExplanationOfBenefit?patient=[patient] GET [base]/ExplanationOfBenefit?type=[code] GET [base]/ExplanationOfBenefit?identifier=[code] GET [base]/ExplanationOfBenefit?service-date=[service-date] |
| Claim | The Claim is used by providers and payors, insurers, to exchange the financial information, and supporting clinical information, regarding the provision of health care services with payors and for reporting to regulatory bodies and firms which provide data analytics. | Query parameters: identifier, patient, insurer, payee |
GET [base]/claim?identifier=[code] GET [base]/claim?patient=[patient] GET [base]/claim?insurer=[insurer] GET [base]/claim?payee=[payee] |
Formulatory Endpoints
Below are the details of the Formulary profiles with their respective search parameters:
| Resource | Definition | Search Parameters | Examples/Combinations |
|---|---|---|---|
| Coverage Plan | A health plan which contains links to administrative information, a list of formulary drugs covered under that plan, and a definition of drug tiers and their associated cost-sharing models. | Query parameters: identifier |
GET [base]/List?identifier=[code] |
| Formulary Drug | Drug information which is part of a formulary | Query parameters: patient |
GET [base]/List?patient=[patient] |
Authorization
Sharp Health Plan Patient Access API is based on the SMART App Launch Framework. Authentication and authorization occurs during the process of granting access to patient data in accordance with OAuth 2.0 specification and OpenID Connect core 1.0 standard. Sharp’s FHIR server supports Proof Key for Code Exchange (PKCE) for Authorization code flow.
You need to follow the instructions on how to Register and Request Access before you can initiate the OAuth flow. During this process you will be asked to provide a redirect_url (or callback url). Sharp Health Plan authorization server supports the Proof Key for Code Exchange (PKCE) authorization flow.
After the registration and request access process, you will be assigned a client id and client secret.
Proof Key for Code Exchange (PKCE) flow
Auth 2.0 public clients utilizing the Authorization Code Grant are susceptible to the authorization code interception attack. For public clients, such as native mobile application OAuth 2.0 supports the PKCE extension and enables custom URIs as redirects and also mitigates the threat of a “man-in-the-middle” attack.
- In the PKCE authorization code flow, your application will need to generate a random string, also called code_verifier and generate a hash (SHA256 + BASE64URL), also called code_challenge on this string. S256 will be referred to as the code_challenge_method.
- Your application must submit a request to the Authorization server’s /authorize with the following parameters
- response_type
- client_id
- redirect_uri
- scope
- state
- code challenge
- code_challenge_method
GET https://identity.aws.sharp.com/as/authorization.oauth2?response_type=code&state=123456&client_id=XYZ...123&scope=openid%20patient/*.read&redirect_uri=https%3A%2F%2Flocalhost%2Fv1%2Fcallback&code_challenge=XYZ1230KlU&code_challenge_method=S256
- The following scopes are supported currently:
- patient/*.read : Permission to read any resource for the current patient/member
- openid: Permits to read patient id of logged in user
- fhirUser: Permits to read patient id of logged in user
- launch/patient: Standalone patient launch mode is only supported
- offline_access: Support “permission-offline” “SMART on FHIR Core Capability”
- online_access
- The member will be directed to Sharp Health Plan login page.
- On successful authentication, the member will be asked for consent.
- On successful authentication and authorization by member, your application will be provided with an authorization code
GET https://localhost/callback?code=XYZ123ABC- Your application must use this authorization code to request token from the /token endpoint
- grant_type
- code
- redirect_uri
- code_verifier
POST https://identity-dev.aws-nonprod.sharp.com/as/token.oauth2 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic YW123XYZ0ZQ==
grant_type=authorization_code
&code=XYZ...123
&redirect_uri=https://localhost/callback
&code_verifier=123...123- The response from the authorization server will contain the below
- access_token
- token_type
- id_token (if openid is requested)
- refresh_token (valid for a period of no shorter than three months)
- expires_in
Content-Type: application/json
{
"access_token": "XYZ123",
"refresh_token": "ABC321",
"id_token": “EFG1234",
"token_type": "Bearer",
"expires_in": 7199
}- You can now use the access_token in your calls to the Sharp Health Plan Patient Access APIs.
- Refresh token is valid for 90 days.