Documentation

Overview

Welcome to the Healthfirst Developer Portal! The portal will lead you through the process to gain access to the Healthfirst APIs. The APIs are HL7 FHIR R4 compliant and use the OAuth 2.0 standard and OpenID Connect 1.0 protocols for authorization and authentication. The following documentation is intended to help developers integrate the Healthfirst APIs into their applications. Healthfirst provides two APIs that developers can integrate with their application:

  • The Patient Access API allows Healthfirst members to access current formularies, their claims and encounter data, as well as a defined subset of their clinical data dating back to January 1st, 2016.
  • The Provider Directory API is a public facing API that allows consumers to search for in-network Healthfirst providers and pharmacies.

Getting Started

This section will detail the steps to integrate your application into the Healthfirst sandbox and production environments.

Integrate your Application with the Sandbox Environment

The Healthfirst sandbox environment is a place where developers can build and test applications using synthetic data.

To integrate your application with the Healthfirst APIs in the sandbox environment:

  1. Click on the Request Form tab at the top of this page and fill out the Third Party Sandbox Request Form.
  2. Healthfirst will respond to your request within 1-2 business days of submission. The email response from Interoperability@Healthfirst.org will include three things:
    • The Client ID for your application that has been granted access to the Patient Access API in the sandbox environment.
    • The details needed to access the sandbox environment for your application.
    • The requirements to promote your application to the production environment
  3. The public sandbox endpoint for the Provider Directory API is https://hf-fhir-provider-directory-sys-api-prod.us-e1.cloudhub.io

Sandbox Sample Users

The following are sample users you can use to login with inside the sandbox environment:

    • Username
    • HFUser00000
    • HFUser00001
    • HFUser00002
    • HFUser00003
    • HFUser00004
    • HFUser00005
    • Password
    • HfPW00000!
    • HfPW00001!
    • HfPW00002!
    • HfPW00003!
    • HfPW00004!
    • HfPW00005!

Integrate your Application with the Production Environment

When you are ready to move your application into production, follow the steps outlined in the response email from Interoperability@Healthfirst.org to gain access to the production environment.

  1. You must send an email to Interoperability@Healthfirst.org with the required information about your application.
  2. After reviewing your email with the required information, Healthfirst may send you an invite link to a video conference meeting to review your application before providing you access to the production environment.
  3. Healthfirst will send you an email from Interoperability@Healthfirst.org with the following information:
    • The Client ID for your application that has been granted access to the Patient Access API in the production environment.
    • The details needed to access the production environment for your application.
  4. The public production endpoint for the Provider Directory API is https://hf-fhir-provider-directory-sys-api-prod.us-e1.cloudhub.io

Authorization

The Patient Access API endpoint requires the OAuth 2.0 and OpenID Connect 1.0 flow with a consent page to retrieve the Access token and ID token for the member that consents. The flow starts with the member logging into the authorization endpoint and consenting to share their data. Once the member consents, the response to the authorization endpoint returns an authorization code in the redirect URI that can be used to retrieve the Access token and ID token. The ID token, when decoded, contains the member name and the member ID. The Access token will be used to authorize the Patient, ExplanationOfBenefit, and Coverage resources with the scope of patient/*.read. The Access token, when decoded will also contain the member ID.

We support the following grant types: Authorization Code or Authorization Code with Proof Key for Code Exchange (PKCE). The Authorization Code flow is traditionally used for public web applications and the Authorization Code Flow + PKCE flow is traditionally used for native applications such as mobile apps.

Authorization Endpoint

Authorization Code Flow

If you are using the Authorization Code flow, here are all the available query parameters:

    • Name
    • response_type
    • scope
    • client_id
    • redirect_uri
    • state
    • Required
    • Yes
    • Yes
    • Yes
    • Yes
    • No
    • Example
    • response_type=code
    • scope=openid+profile+patient/*.read+launch/patient
    • client_id=myclientid
    • redirect_uri=http://localhost:8082/myapp
    • state=af0ifjsldkj
    • Description
    • The response type is always code.
    • The scope is always openid+profile+patient/*.read+launch/patient
    • The client id of your application that you registered
    • The redirect uri that the web application redirects to after a successful authorization
    • The state parameter is used to protect against XSRF attacks

Authorization Code Flow with Proof Key for Code Exchange (PKCE)

If you are using the Authorization Code flow with PKCE, here are all the available query parameters:

    • Name
    • response_type
    • scope
    • client_id
    • redirect_uri
    • code_challenge
    • code_challenge_method
    • state
    • Required
    • Yes
    • Yes
    • Yes
    • Yes
    • Yes
    • Yes
    • No
    • Example
    • response_type=code
    • scope=openid+profile+patient/*.read+launch/patient
    • client_id=myclientid
    • redirect_uri=http://localhost:8082/myapp
    • code_challenge=6VLmPKYqeh3cl/YKXLbeOLfF0SiR3/38pQC6ozldmXs
    • code_challenge_method=S256
    • state=af0ifjsldkj
    • Description
    • The response type is always code.
    • The scope is always openid+profile+patient/*.read+launch/patient
    • The client id of your application that you registered
    • The redirect uri that the web application redirects to after a successful authorization
    • A base 64 url encoded string of the SHA-256 hash of the code verifier string.
    • We only support the S256 code challenge method.
    • The state parameter is used to protect against XSRF attacks

Step 1: Retrieving the authorization code

Once the Healthfirst member clicks on the authorization endpoint URL, they will be presented with a login page. The Healthfirst member will then login using their Healthfirst credentials and consent to sharing their data with you (the 3rd party developer). After the Healthfirst member consents, your application will be authorized to receive their data. The application will then redirect to your redirect URI and will contain a query parameter “code”. The query parameter “code” can then be exchanged for the Access and ID tokens in Step 2.

Step 2: Retrieving the access and id tokens

Once you have the code from the redirect URI query parameter, you can now call the token endpoint.

The token endpoint is POST https://platform.smcpartners.com/healthfirst/smartauth/oauth/token

The token endpoint has a body of type www-form-url-encoded

Here are the keys and values needed to insert as part of the www-form-url-encoded body:

    • Key
    • client_id
    • grant_type
    • code
    • redirect_uri
    • scope
    • code_verifier
    • Value
    • The client id of your application that was issued to you by Healthfirst
    • The value will always be authorization_code even if the flow contains PKCE
    • The code returned as the query param of your redirect uri after the customer authorized your application
    • The redirect uri of your app. It must match what you passed into the authorization endpoint
    • The scope is always openid profile patient/*.read launch/patient
    • Only required if using PKCE. The original string to verify against before it was hashed and base 64 encoded.
    • Example Value
    • myclientid
    • authorization_code
    • client_id=myclientid
    • http://localhost:8082/myapp
    • openid profile patient/*.read launch/patient
    • d93i4uggdiuf8p4or0Au

The response returned from the token endpoint call contains the access_token and id_token and patient fields. The patient field value in the token endpoint response is the member ID. You can also retrieve the member ID by decoding the id_token JWT or access_token JWT. The member ID is the value of the “profile” key in the id_token JWT and the member ID is the value of the “patient” field in the access_token JWT. A refresh_token field is also included which allows you to refresh the access token after it expires (The access token expires after 3600 seconds or 60 minutes). To use the refresh token, invoke the token endpoint again with the grant_type “refresh_token” instead of “authorization_code” and also pass in a new key called “refresh_token” with the refresh token value.

Patient Access

Coverage

The Coverage resource provides information about a patient’s coverage/insurance plans. This information is usually found on an insurance card.

GET /Coverage

Parameters

    • Parameter Type
    • query
    • query
    • Name
    • _id
    • patient
    • Type
    • String
    • String
    • Description
    • The id of the Coverage resource
    • The reference to the patient

GET /Coverage/{_id}

Parameters

    • Parameter Type
    • path
    • Name
    • _id
    • Type
    • String
    • Description
    • The id of the Coverage resource

Explanation Of Benefit

The ExplanationOfBenefit (EOB) resource combines claim information, adjudication information, and, optionally, account information for a patient.

GET /ExplanationOfBenefit

Parameters

    • Parameter Type
    • query
    • query
    • query
    • query
    • Name
    • _id
    • patient
    • service-date
    • type
    • Type
    • String
    • String
    • String
    • String
    • Description
    • The id of the ExplanationOfBenefit resource
    • The reference to the patient
    • Include resources that completed in the given range
    • A list of claim types to include

GET /ExplanationOfBenefit/{_id}

Parameters

    • Parameter Type
    • path
    • Name
    • _id
    • Type
    • String
    • Description
    • The id of the ExplanationOfBenefit resource

Patient

The Patient resource contains demographic information about a member who receives healthcare services.

GET /Patient

Parameters

    • Parameter Type
    • query
    • query
    • Name
    • _id
    • identifier
    • Type
    • String
    • String
    • Description
    • The id of the Patient resource
    • A patient identifier

GET /Patient/{_id}

Parameters

    • Parameter Type
    • path
    • Name
    • _id
    • Type
    • String
    • Description
    • The id of the Patient resource

Provider Directory

HealthcareService

The HealthcareService resource contains details of a healthcare service available at a location.

GET /HealthcareService

Parameters

    • Parameter Type
    • query
    • query
    • Name
    • _id
    • specialty
    • Type
    • String
    • String
    • Description
    • The id of the HealthcareService resource
    • The specialty of the service provided by this healthcare service

GET /HealthcareService/{_id}

Parameters

    • Parameter Type
    • path
    • Name
    • _id
    • Type
    • String
    • Description
    • The id of the HealthcareService resource

Organization

The Organization resource is used for formally or informally recognizing a grouping of people or organizations that are formed for the purpose of achieving some form of collective action. Includes companies, institutions, corporations, departments, community groups, healthcare practice groups, payer/insurer, etc.

GET /Organization

Parameters

    • Parameter Type
    • query
    • query
    • query
    • Name
    • _id
    • name
    • address
    • Type
    • String
    • String
    • String
    • Description
    • The id of the Organization resource
    • A portion of the organization’s name or alias
    • A server defined search that may match any of the string fields in the Address, including line, city, district, state, country, postalCode, and/or text

GET /Organization/{_id}

Parameters

    • Parameter Type
    • path
    • Name
    • _id
    • Type
    • String
    • Description
    • The id of the Organization resource

Location

The Location resource contains details and position information for a physical place where services are provided and resources and participants may be stored, found, contained, or accommodated.

GET /Location

Parameters

    • Parameter Type
    • query
    • query
    • Name
    • _id
    • address
    • Type
    • String
    • String
    • Description
    • The id of the Location resource
    • A (part of the) address of the location

GET /Location/{_id}

Parameters

    • Parameter Type
    • path
    • Name
    • _id
    • Type
    • String
    • Description
    • The id of the Location resource

Practitioner

A Practitioner resource is a person who is directly or indirectly involved in the provisioning of healthcare.

GET /Practitioner

Parameters

    • Parameter Type
    • query
    • query
    • query
    • Name
    • _id
    • name
    • address
    • Type
    • String
    • String
    • String
    • Description
    • The id of the Practitioner resource
    • The name of the Practitioner that is able to provide the defined services for the organization
    • A server defined search that may match any of the string fields in the Address, including line, city, district, state, country, postalCode, and/or text

GET /Practitioner/{_id}

Parameters

    • Parameter Type
    • path
    • Name
    • _id
    • Type
    • String
    • Description
    • The id of the Practitioner resource

Practitioner Role

A PractitionerRole is a specific set of roles/locations/specialties/services that a practitioner may perform at an organization for a period of time.

GET /PractitionerRole

Parameters

    • Parameter Type
    • query
    • query
    • query
    • query
    • query
    • query
    • Name
    • _id
    • practitioner.name
    • practitioner.id
    • location.address
    • organization.address
    • specialty
    • Type
    • String
    • String
    • String
    • String
    • String
    • String
    • Description
    • The id of the PractitionerRole resource
    • The name of the practitioner that is able to provide the defined services for the organization
    • The id associated with the Healthfirst practitioner
    • The address of the practitioner
    • The address of the organization the practitioner represents/acts on behalf of
    • The specialty a practitioner has at an organization

GET /PractitionerRole/{_id}

Parameters

    • Parameter Type
    • path
    • Name
    • _id
    • Type
    • String
    • Description
    • The id of the Practitioner Role resource

Privacy and Terms of Service

The Healthfirst Terms of Service can be accessed here.

The Healthfirst Privacy Policy can be accessed here.

Contact Us

For questions or concerns please contact Healthfirst at Interoperability@Healthfirst.org