Patient Access and Interoperability

Getting Started: 3rd Party Application Instructions


Welcome! The page provides information on how to access to our APIs, which are based on the Health Level 7® (HL7) Fast Healthcare Interoperability Resources (FHIR®) 4.0.1 standards.

There are two APIs, giving you the ability to build applications for our customers and providers based on the following.
  • The Member/Patient Access API allows customers to access their claims and encounter information (including cost), and a sub-set of their clinical information. 
  • The Provider Directory API facilitates searches for providers, allowing providers to search for other in-network providers.
The Provider API allows:
  • Look up providers by specialty and/or location.
  • Look up a provider's office hours and location.
  • Determine whether a provider is accepting new patients.
  • Find specialists that are in-network and the hospital they are associated with.
  • Discover what specialties a local hospital provides.
  • Locate in-network pharmacies and their hours of operation.
Below are the 3rd party application requirements to help you get your developer account registered and your application authorized, including steps on how to get your application connected to the FHIR server. Included is information on the how the FHIR spec is implemented.

3rd Party Application Requirements

Follow these steps to register your application and get it authorized, so you can begin building your application.
  1. Register your application...
    Developer Registration
  2. Provide the details for your application. In the application registration form, you will be asked to provide the name of your application, the callback URL and the scopes (currently, the following scopes are available and enabled by default: patient/*.read, openid and fhirUser).
  3. You will receive an email when your application is approved
  4. After you your application is approved, you will be given a Client ID and Client Secret for your application. You will need these (along with the callback URL and scope) to use during authentication.
Note: If you fail to store your application's Client ID and Client Secret, you will have to restart the application registration process.
 
  1. Start using the APIs with your newly registered application. Once you have successfully registered your application, you can begin using the APIs.

How to Connect

Follow these steps to use your application's Client ID, Client Secret, authorization codes, and tokens to securely connect your application to the Consumer Access API.

Authorization Overview
The Member/Patient Access API is based on the FHIR SMART app framework, and relies on the OAuth 2.0 specification and the OpenID Connect Core 1.0 standard for securing connections. The FHIR server supports both the standard OAuth 2.0 and OIDC web application authorization flow and the Proof Key for Code Exchange (PKCE) authorization flow.

Application Registration
To begin, you must first register your application. When you register your application, you will need to have a callback URL (aka redirect URI) to assign to your application, which will be used during the authorization flow. If you will be creating a mobile application, or a web application that cannot securely store the Client Secret, 

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 your authorized endpoint: https://fhir.group-health.com/api
 
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.

Your privacy policy
You will be asked to provide a URL to your privacy policy when registering your organization and your application in the Interoperability App Owner Portal. These links should be easy to access and understand by a member using your app.

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.

FHIR RESTful API Capabilities
  • Implements RESTful behaviors according to the FHIR specification.
  • 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


Implementation Guides Supported Profiles
Base URL
The base url for each endpoint is:  https://fhir.group-health.com/api

Each application will have a unique base URL to access its Authorization Server. The required endpoint URLs are as follows:
 
ENDPOINT URL
Authorization https://ghclogin.b2clogin.com/ghclogin.onmicrosoft.com/<policy-name>/oauth2/v2.0/authorize
Token https://ghclogin.b2clogin.com/ghclogin.onmicrosoft.com/<policy-name>/oauth2/v2.0/token
 
When the end user is directed to the authorization endpoint, the user will be presented with a login screen where they can enter their credentials for the healthcare organization they are accessing. If the correct credentials are supplied and the end user grants access to the client application, an authorization code will be returned to the client that the client application can use to obtain an access token through the token endpoint.

All requests to the API must include the access token transmitted in the Authorization header of the HTTP request as a bearer token as illustrated in RFC 6749. If the access token is missing, expired, or otherwise not valid for the requested operation, the API will return a 401 Unauthorized response.
Below are the FHIR Endpoints: https://fhir.group-health.com/api

 
1) Endpoint

https://fhir.group-health.com/api/plannet/
Key Value
  id 5751535189661177282
_lastUpdated 20210319 044421.080
meta.profile http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Endpoint
name Endpoint
address https://fhir.group-health.com/api
        
2) HealthcareService: The Healthcare Service resource typically describes services offered by an organization/practitioner at a location. The resource may be used to encompass a variety of services covering the entire healthcare spectrum, including promotion, prevention, diagnostics, hospital and ambulatory care, home care, long-term care, and other health-related and community services.  

https://fhir.group-health.com/api/plannet/healthcareservice
Key Value
  id 8255303642851900000
_lastUpdated 20210322 135044.124
meta.profile http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-HealthcareService
name TEST, HiPaaS
location Location/5240889202256475099
specialty https://fhir.group-health.com/api/hipaas/provider-taxonomy
service-category http://hl7.org/fhir/us/davinci-pdex-plan-net/CodeSystem/HealthcareServiceCategoryCS

3) InsurancePlan: Insurance Plan describes a health insurance offering comprised of a list of covered benefits (for example: the product), costs associated with those benefits (for example: the plan), and additional information about the offering, such as who it is owned and administered by, a coverage area, contact information, etc.  

https://fhir.group-health.com/api/plannet/insuranceplan
                Key Value
  Id 5259084001070903454
_lastUpdated 20210319 044421.156
meta.profile http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-InsurancePlan
name DHCS
administered-by Organization/2643920332232162708
owned-by Organization/6711270871498486941
coverage-area Location/6439372744080560247
plan-type http://hl7.org/fhir/us/davinci-pdex-plan-net/CodeSystem/InsurancePlanTypeCS
type http://hl7.org/fhir/us/davinci-pdex-plan-net/CodeSystem/InsuranceProductTypeCS

4)  Location:  A Location is the physical place where healthcare services are provided, practitioners are employed, organizations are based, etc. Locations can range in scope from a room in a building to a geographic region/area.  

https://fhir.group-health.com/api/plannet/location
Key Value
  id 5240889202256475099
_lastUpdated 20210317 073313.285
meta.profile http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Location
name HiPaaS TEST, LMFT ATRBC Art for Access
address 123 TEST Street STE 200C
address-postalcode 94527
address-state CA
address-city Concord
type http://terminology.hl7.org/CodeSystem/v3-RoleCode

5) Organization:

A Network refers to a healthcare provider insurance network. A healthcare provider insurance network is an aggregation of organizations and individuals that deliver a set of services across a geography through health insurance products/plans. A network is typically owned by a payer. An Organization refers to 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.

https://fhir.group-health.com/api/plannet/organization
Key Value
  id 4802000587909300000
lastUpdated 20210317 070944.584
meta.profile http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Organization
name TEST, HiPaaS
address 123 TEST Street
address-postalcode 94527
address-state CA
address-city CONCORD
type http://hl7.org/fhir/us/davinci-pdex-plan-net/CodeSystem/OrgTypeCS
 
 
6) OrganizationAffiliation:
The OrganizationAffiliation resource describes relationships between two or more organizations, including the services one organization provides another, the location(s) where they provide services, the availability of those services, electronic endpoints, and other relevant information.

https://fhir.group-health.com/api/plannet/organizationaffiliation
    Key Value
  id 2655074298945687219
_lastUpdated 20210317 111720.712
meta.profile http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-OrganizationAffiliation
primary-organization Organization/2105939142400949903
participating-organization Organization/2105939142400949903
location Location/5240889202256475099
network Organization/123456
 
 
7) Practitioner:
A Practitioner is a person who is directly or indirectly involved in the provisioning of healthcare. The DaVinci PDEX Plan-Net Practitioner profile is based on the core FHIR US Core Practitioner resource.
 
https://fhir.group-health.com/api/plannet/practitioner
     Key Value
  id 8D32FCA7-F4EC-423D-93B8-000C26900000
_lastUpdated 20210401 160100.978
meta.profile http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Practitioner
family  HEALTH MEDICAL CENTER
identifier.value 18535258621
identifier.system https://fhir.group-health.com/api/hipaas/npi
 
 
8) PractitionerRole:
A specific set of Roles/Locations/specialties/services that a practitioner may perform at an organization for a period of time.The DaVinci PDEX Plan-Net PractitionerRole profile is based on the core FHIR PractitionerRole resource.

https://fhir.group-health.com/api/plannet/practitionerrole
                                           Key Value
  id 8160106400499867011
_lastUpdated 20210322 074912.539
meta.profile http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-HealthcareService
practitioner Practitioner/1402157620721263560
organization Organization/4802000587909327601
location Location/2957802095982738323
   
 
 
Member/Patient Data information:

9) ExplanationOfBenefit:
Explanation of Benefits (EOB) for professional, institutional, and pharmacy claims

https://fhir.group-health.com/api/ExplanationOfBenefit
Key Value
  id EB06D430-BE27-4981-A7B4-002EEEA5EBD2
_lastUpdated 20210401 110036.005
meta.profile https://www.hl7.org/fhir/explanationofbenefit.html
 

10) Coverage

https://fhir.group-health.com/api/Coverage
Key Value
  id D019186F-DEE5-4FC9-B6B9-001980500000
_lastUpdated 20210402 045806.302
meta.profile http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Coverage
type http://terminology.hl7.org/CodeSystem/v3-ActCode
subscriberId 95911354F
dependent 01
 

11) Patient

https://fhir.group-health.com/api/Patient
https://fhir.group-health.com/api/Patient/{id}
Key Value
  id A020B46E-8258-4396-876C-0059BADBED9C
_lastUpdated 20210402 074202.160
meta.profile http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Patient
family TEST
given HiPaaS
birthDate 2020-08-19 00:00:00.0000000
address-city Pleasanton
address-state CA
address-postalcode 94527
gender F
 
 

Developer Registration