Patient Access
Overview
The Patient Access API is used to build applications that enable Alliance members to easily access their claims and encounter information (including cost), as well as a defined sub-set of their clinical information. This is a RESTful API that conforms to the FHIR standard and provides access to an Alliance member's data.
This section describes the FHIR profiles, resources and RESTful capabilities that the Patient Access API supports. A profile is a set of rules which allows a resource to be constrained, or to include extensions, so the resource can add additional attributes. The RESTful capabilities are discussed in further detail below.
Implementation Notes
This specification uses SHALL, SHOULD y MAY as a guideline for required, recommended and optional data FHIR standards.
- SHALL: An absolute requirement for all implementations. The FHIR server must return this data.
- SHOULD: A best practice or recommendation for the implementation. The FHIR server is recommended to return this data.
- MAY: An optional inclusion for the implementation; not a requirement. The FHIR server may return the data, but there is no requirement to do so.
3rd Party App Requirements: Developer Application Registration
Follow these steps to register your developer account and get your application authorized so you can begin building your application.
- Register your developer account by completing the Developer Application Form on the Alliance website. The form asks for the name of your application, the callback URL, the scopes, and other relevant information.
- The Alliance team will perform security review and audit based on information submitted in your application form.
- You will receive an email within 5 business days indicating your approval status.
- Once approved, the Alliance provides you with a Client ID y Client Secret, which you need (along with the callback URL and scope) to use during authentication.
- Start using APIs with your newly registered application. Once you have successfully registered your application, you can begin using the APIs.
Security
All Alliance patient access transactions must be secured appropriately, and directed by regulations, with access limited to authorized individuals, data protected, and appropriate audit measures taken.
How to Connect
The information below describes how to use your application's Client ID, Client Secret, authorization codes, and tokens to securely connect your application to the Patient Access API.
Authorization Overview
The FHIR server supports the standard OAuth 2.0 C web application authorization flow.
Standard Authorization Code Flow
In the standard authorization code flow, to connect to the Member/Patient Access API, you will need to use the OAuth 2.0 and OpenID Connect (OIDC) flow for authentication. This flow should only be used by sites that can safely protect the Client ID and Client Secret, such as a site running on a secure server.
Request Authorization from User
To allow a user to authorize your application, direct them to our authorization server with your Client ID and callback URL. If the user consents, we will redirect back to your callback URL.
Exchange Code for Token
After sending the authorization request, the customer will be directed to a sign in page through browser re-directs, where they will provide their credentials to authenticate themselves. Upon completing sign-in, the customer will be presented with an authorization page. Once the customer authorizes your application, your application can now exchange the code provided.
Authorization, Authentication, and Registration
Client applications and systems of record SHALL support the standalone launch sequence of the SMART App Launch framework for user authorization and client authentication. Systems of record SHALL publish their authorization and token endpoints for discovery in accordance with the SMART App Launch framework.
Security Guidelines
As per the implementation guide, security guidelines are as follows:
- Systems SHALL establish a risk analysis and management regime that conforms with HIPAA security regulatory requirements.
- Systems SHALL keep audit logs of the various transactions.
FHIR RESTful API Capabilities
- Implements RESTful behaviors according to the FHIR specification.
- Supports JSON source formats for all US Core interactions.
- Returns the following http status codes:
| HTTP Status Code | Description |
| 200 | Successful Request |
| 400 | Invalid Parameter |
| 401 | Not Authorized |
| 403 | Insufficient Scope |
| 404 | Unknown Resource |
| 410 | Deleted Resource |
Patient Access Resources
These are the endpoints and resources available with the Patient Access API. The Patient Access API supports the following FHIR approved implementation guides, and supports the following profiles:
Implementation Guides
- US Core Implementation Guide Version 3.1.1
- CARIN Consumer Directed Payer Data Exchange Implementation Guide Version 1.0.0
- DaVinci Payer Data Exchange Implementation Guide Version 1.0.0
- DaVinci Payer Data Exchange US Drug Formulary Implementation Guide Version 1.0.0
Supported Profiles
Base URL
The base URL for each endpoint is: [The Patient Access platform is being retooled and this link will be available soon]
1) Coverage
El programa Coverage resource is intended to provide the high-level identifiers and descriptors of an insurance plan, typically the information which would appear on an insurance card, which may be used to pay, in part or in whole, for the provision of health care products and services.
Supports the CARIN BB Coverage Profile.
[The Patient Access platform is being retooled and this link will be available soon]
| Key | Value |
| _lastUpdated | 2022-02-23T08:15:31Z |
| meta.profile | http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Coverage|1.1.0 |
| type | HIP |
| subscriberId | 111111111 |
| dependent | 01 |
Interactions
- Read:
GET [base]/Coverage/[id]
- Search:
GET [base]/Coverage?{parameters...}
Search Parameters
| Search Parameter | Search Parameter Type | Ejemplo |
| patient | reference | GET \[base]/Coverage?patient=[patient] |
| _lastUpdated | date | GET \[base]/Coverage?_lastUpdated=[_lastUpdated] |
Supported includes & revIncludes
| _include | _revInclude |
| Coverage:payor | N/A |
2) DiagnosticReport
A diagnostic report, which can be a combination of request information, atomic results, images, interpretation, as well as formatted reports.
The US Core Diagnostic Report Profile is based upon the core FHIR DiagnosticReport Resource and created to meet the 2015 Edition Common Clinical Data Set “Laboratory test(s) and Laboratory value(s)/result(s)” requirements, and supports the US Core DiagnosticReport Profile for Report and Note exchange y US Core DiagnosticReport Profile for Laboratory Results Reporting.
[The Patient Access platform is being retooled and this link will be available soon]
| Key | Value |
| status | final |
| resourceType | DiagnosticReport |
| effectiveDateTime | 2022-01-10 |
Search Parameters
| Search Parameter | Search Parameter Type | Ejemplo |
| category | token | GET \[base]/DiagnosticReport?category=[category] |
| code | token | GET \[base]/DiagnosticReport?code=[code] |
| date | date | GET \[base]/DiagnosticReport?date=[date] |
| patient | reference | GET \[base]/DiagnosticReport?patient=[patient] |
| _lastUpdated | date | GET \[base]/DiagnosticReport?_lastUpdated=[_lastUpdated] |
Supported includes & revIncludes
| _include | _revInclude |
| N/A | Provenance:target |
3) ExplanationOfBenefit
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.
The ExplanationOfBenefit resources can represent a Patient, Provider, Insurer, Care Team, Facility and Coverage with references to Patient, Organization, Practitioner, PractitionerRole, Location and Coverage resources. The Alliance FHIR server is capable of returning all Patient, Practitioner, Organization, PractitionerRole, Location and Coverage resources for an ExplanationOfBenefit via the _id of the reference resource.
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.
[The Patient Access platform is being retooled and this link will be available soon]
| Key | Value |
| _lastUpdated | 2022-02-23T11:06:09Z |
| meta.profile | http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-ExplanationOfBenefit-Inpatient-Institutional|1.1.0 |
| type | institutional |
| identifier.value | 20220300QYBBRTOR |
Interactions
- Read:
GET [base]/ExplanationOfBenefit/[patient]
- Search:
GET [base]/ExplanationOfBenefit?[{parameters...}
Search Parameters
| Search Parameter | Search Parameter Type | Ejemplo |
| _id | token | GET \[base]/ExplanationOfBenefit?_id=[id] |
| patient | reference | GET \[base]/ExplanationOfBenefit?patient=[patient] |
| type | token | GET \[base]/ExplanationOfBenefit?type=[system][code] |
| identifier | token | GET \[base]/ExplanationOfBenefit?identifier=[system][code] |
| service-date | date | GET \[base]/ExplanationOfBenefit?service-date=[service-date] |
| _lastUpdated | date | GET \[base]/ExplanationOfBenefit?_lastUpdated=[_lastUpdated] |
Supported includes & revIncludes
| _include | _revInclude |
| ExplanationOfBenefit:* | N/A |
| ExplanationOfBenefit:care-team | |
| ExplanationOfBenefit:coverage | |
| ExplanationOfBenefit:insurer | |
| ExplanationOfBenefit:patient | |
| ExplanationOfBenefit:provider |
4) 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.
El programa US Core Immunization Profile is based upon the core FHIR Immunization resource and created to meet the 2015 Edition Common Clinical Data Set “Immunizations” requirements.
[The Patient Access platform is being retooled and this link will be available soon]
| Key | Value |
| status | completed |
| resourceType | Immunization |
| occurrenceDateTime | 2022-02-09 |
Interactions
- Read:
GET [base]/Immunization/[id]
- Search:
GET [base]/Immunization?{parameters...}
Search Parameters
| Search Parameter | Search Parameter Type | Ejemplo |
| patient | reference | GET \[base]/Immunization?patient=[patient] |
| _lastUpdated | date | GET \[base]/Immunization?_lastUpdated=[_lastUpdated] |
Supported includes & revIncludes
| _include | _revInclude |
| N/A | Provenance:target |
5) 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.
El programa US Core Organization Profile is based on the core FHIR Organization resource. This resource is also based on the CARIN BB Organization Profile.
[The Patient Access platform is being retooled and this link will be available soon]
Interactions
- Read:
GET [base]/Organization/[id]
Search Parameters
- N/A
Supported includes & revIncludes
| _include | _revInclude |
| N/A | N/A |
6) Patient
Information about an individual receiving health care services. The US Core Patient Profile is based upon the core FHIR Patient resource and designed to meet the applicable patient demographic data elements from the 2015 Edition Common Clinical Data Set. This resource is also based on the CARIN BB Patient Profile.
[The Patient Access platform is being retooled and this link will be available soon]
| Key | Value |
| _lastUpdated | 2022-01-07T11:59:54Z |
| meta.profile | http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Patient |
| family | Default |
| given | Member |
| birthDate | 1950-01-01 |
| address-city | NEW YORK |
| address-state | NY |
| address-postalcode | 10001 |
| address | 123 Maine Rd |
| gender | male |
Interactions
- Read:
GET [base]/Patient/[id]
- Search:
GET [base]/Patient?{parameters...}
Operations
Operation
Ejemplo
GET [base]/Patient/:id/$everything
Body
N/A
Operation
Ejemplo
POST [base]/Patient/:id/$health-cards-issue
Body
{"resourceType": "Parameters",
"parameter": [{
"name": "credentialType",
"valueUri": "https://smarthealth.cards#covid19"}, {
"name": "credentialType",
"valueUri": "https://smarthealth.cards#immunization" }]}
Search Parameters
| Search Parameter | Search Parameter Type | Ejemplo |
| _id | token | GET \[base]/Patient?_id=[_id] |
| birthdate | date | GET \[base]/Patient?birthdate=[birthdate] |
| gender | token | GET \[base]/Patient?gender=[gender] |
| identifier | token | GET \[base]/Patient?identifier=[identifier] |
| name | string | GET \[base]/Patient?name=[name] |
| _lastUpdated | date | GET \[base]/Patient?_lastUpdated=[_lastUpdated] |
Supported includes & revIncludes
| _include | _revInclude |
| N/A | Provenance:target |
7) Practitioner
A person with a formal responsibility in the provisioning of healthcare or related services.
El programa US Core Practitioner Profile is based on the core FHIR Practitioner resource. This resource is also based on the CARIN BB Practitioner Profile.
[The Patient Access platform is being retooled and this link will be available soon]
Interactions
- Read:
GET [base]/Practitioner/[id]
Search Parameters
- N/A
Supported includes & revIncludes
| _include | _revInclude |
| N/A | N/A |
