UnitedHealthcare Interoperability APIs

To use the UnitedHealthcare interoperability API OAuth 2 a developer must register their application. An organization must register as a user by creating an OneHealthcare ID and complete the registration application through the “App Owner” section of the Vendor Portal before the ability to register applications is accessible.

A registered application is given a client ID and a client secret. The secret should only be used if it can be kept confidential, such as communication between your server and the UnitedHealthcare interoperability APIs. For insecure implementations, such as mobile apps, PKCE (Proof Key for Code Exchange) is available.

Access tokens have scopes, which define permissions and the resources that the token can access. Scopes are primarily utilized to determine the type of data an application is requesting. Scopes must be explicitly declared; wildcards are not supported. In the current release the following scopes are available for the following types of requests: 

Note: Any Scope not currently listed is not supported

Provider directory

This gives access to the correct FHIR Endpoints.

Our OAuth2 authentication screen requires members consent to share different types of data. Your application will need to handle the return of a HTTP status codes from the endpoints if there are authentication or configuration failures.

If the member declines to share information that your application needs, you may display a message explaining why that information is needed and request re-authorization, or handle the collection of that information elsewhere within your application.

The default selection will be to share the scopes included in the initial request with your application. If a member declines a scope but later decides they want to change that selection, they’ll need to re-authenticate and make a different choice from the OAuth2 screen.

If information limited by a scope is required for your application to properly function and it is not possible to get the information in another endpoint, we recommend providing an explanation about why certain data is needed in your user flow. For example, if you use demographic information to help members autofill tedious data-entry, you might want to explain that benefit before they reach the authorization screen. It is essential, however, that you give members the full picture. If they do share data with your application, they should know how long you keep it and if it is used for any other purposes.

Use this table to populate the [payer] annotations in any URL below.

For public clients, such as native mobile application OAuth 2.0 supports the PKCE extension and enables custom URIs as redirects.

The implementation of the PKCE specification enables developers to build mobile applications without requiring a proxy server to route redirect calls to their mobile app.

The PKCE extension provides a technique for public clients to mitigate the threat of a “man-in-the-middle” attack. This involves creating a “secret” that is used when exchanging the authorization code to obtain an access token.

PKCE uses a code challenge that is derived from a code-verifier. UnitedHealthcare interoperability API 2.0 supports the “S256” style code challenge.

Where the:

The following additional parameters and values are sent as part of the OAuth2.0 Authorization Request:

• code_challenge
• codechallengemethod = “S256”

The redirect_uri supports any URI protocol. See examples below:

• https:// protocol
• custom_uri:// protocol

The https:// format is used for secure communication and is required for all applications in the production environment unless the application is using the Mobile OAuth method for handling callbacks.

The custom_uri protocol is used by mobile applications to handle communications directly with your application on a mobile device.

If you are using Mobile OAuth support for communication directly with a mobile device the custom_uri should follow this format:

For example, if the UnitedHealthcare interoperability API team created an application we might create a custom_uri of:

This would then be incorporated into a redirect URI entry. Here is an example:

The following query parameters are required:

• Create a random string to use as the code_verifier:
  eae64b84b53f479d92ab81dce7c8bbe608492951def502d84b4f0cd7
• Create the SHA256 hash, then base64-URL-encode the string:
  hI2vVv0Er_dHX9lUJo2O8lbFzkxfChVyM2WcHfODLnU 
• Use the base64 url-encoded string as the code_challenge parameter value.
• code_challenge_method will always be S256 and each code request must contain a unique code_challenge value.

Example GET Request

GET /oauth/authorize HTTP/1.1 

Host: https://[payer].authz.flex.optum.com

response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=patient/Patient.read%20patient/ExplanationOfBenefit.read%20patient/Procedure.read&state=1234zyx&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

Upon reaching the payer endpoint, the member will be redirected to the respective OAuth2/OIDC Identity Provider (IDP) for their plan.

The member will authenticate with the IDP and will eventually be redirected back to the endpoint provided in the authorization request’s redirect_uri parameter. When the member arrives back to the redirect_uri, the request will contain the following query string parameters:

• code
• state

Compare the state value to the value sent in the initial token request. The values must match or it is an indication of a potential hijack attempt.

The code value will be exchanged for an authorization token by the client application in a background POST request to the AuthZ token endpoint: https://[payer].authz.flex.optum.com/oauth/token

The following POST parameters will be sent:

Sample token request

POST /oauth/token HTTP/1.1

Host: https://[payer].authz.flex.optum.com 

Content-Type: application/x-www-form-urlencoded 

grant_type=authorization_code&code=AUTH_CODE_HERE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code_verifier=CODE_VERIFIER

(choose either client_secret or code_verifier)

The POST response will return a JSON object with the following properties:

Sample token response

Client credentials (system-to-system) and Public access

For system-to-system and public access authentication, the token endpoint supports the client_credentials grant. In this case, the token endpoint is requested, and a token response will be received.

Refresh tokens

The access token will be short-lived, typically 5 minutes or less.

If the data request returns an HTTP 400 response, the access token has likely expired, and the refresh token must be utilized to receive a new access token.

To receive a new access token, POST a request to the above token endpoint with the grant_type=refresh_token and refresh_token= will return a token response with a new access token. A new refresh token will not be issued.

Refresh POST example:

Refresh tokens must be secured. A refresh token is long-lived and may be used to issue access tokens that provide access to a member’s information for the duration of the refresh token’s lifetime.

Using access tokens

Resource requests to the FLEX layer require an OAuth2 authorization token provided in the HTTP Authorization header in the format if the example below:

Base request URL

Metadata capability statement

Well known configuration URL

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, pharmacy, hospital and ambulatory care, home care, long-term care, and other health-related and community services.

Method (read):

GET [base]/HealthcareService/[id]

Method (search):

GET [base]/HealthcareService?service-category=prov

Optional search parameters:

Examples:

GET [base]/HealthcareService?service-category=prov&name=Stewart

GET [base]/HealthcareService?service-category=prov&name=Stewart&specialty=207R00000X

An Insurance Plan is a discrete package of health insurance coverage benefits that are offered under a particular network type. A given payer’s products typically differ by network type and/or covered benefits. A plan pairs a product’s covered benefits with the particular cost sharing structure offered to a consumer. A given product may comprise multiple plans (i.e., each plan offers different cost sharing requirements for the same set of covered benefits).

Method (read):

GET [base]/InsurancePlan/[id]

Method (search):

GET [base]/InsurancePlan

Optional search parameters:

Examples:

GET [base]/InsurancePlan?name=AARP

GET [base]/InsurancePlan?type=mediadv

GET [base]/InsurancePlan?coverage-area=17d3a57ef4bce23a2ea4da87259a7934e99b539

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.

Method (read):

GET [base]/Location/[id]

Method (search):

GET [base]/Location

Optional search parameters:

Examples:

GET [base]/Location?address=Orlando

GET [base]/Location?address-state=CA

GET [base]/Location?address-postalcode=97035-2591

An organization is a formal or informal grouping of people or organizations with a common purpose, such as a company, institution, corporation, community group, or healthcare practice.

Method (search):

GET [base]/Organization/[id]

Method (search):

GET [base]/Organization

Optional search parameters:

Examples:

GET[base]/Organization?partof=Organization/UHC
GET[base]/Organization?name=UnitedHealthcare

GET[base]/Organization?type=prygrp

GET[base]/Organization?_profile=http://hI7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Organization&type=prygrp

A network is a type of organization search using the profile parameter.

Method (search):

GET [base]/ Organization?_profile=http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Network

Optional search parameters:

Examples:

GET [base]/Organization?_profile=http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Network&address=Bahama

GET [base]/Organization?_profile=http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Network&partof=UHC

GET [base]/Organization?_profile=http://hl7.org/fhir/us/davinci-pdex-plan-net/StructureDefinition/plannet-Network&type=ntwk

The Organization Affiliation 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.

Method (search):

GET [base]/OrganizationAffiliation

Optional search parameters:

Examples:

GET [base]/OrganizationAffiliation?specialty=230000000X

GET [base]/OrganizationAffiliation?location.address-city=Orlando

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

Method (read):

GET [base]/Practitioner/[id]

Method (search):

GET [base]/Practitioner

Optional search parameters:

Examples:

GET [base]/Practitioner?name=dice

GET [base]/Practitioner?given=slice

GET [base]/Practitioner?address-state=CA

GET [base]/Practitioner?identifier=123456

Practitioner Role describes details about a provider, which can be a practitioner or an organization. When the provider is a practitioner, there may be a relationship to an organization.

A provider renders services to patients at a location. When the provider is a practitioner, there may also be a relationship to an organization. Practitioner participation in healthcare provider insurance networks may be direct or through their role at an organization.

Method (read):

GET [base]/PractitionerRole/[id]

Method (search):

GET [base]/PractitionerRole

Optional search parameters:

Examples:

GET [base]/PractitionerRole?specialty=340000000X

GET [base]/PractitionerRole?location.address-state =CA

Demographics and other administrative information about an individual or animal receiving care or other health-related services. The $match operation returns a Bundle. This bundle will contain either one Patient resource or one OperationOutcome resource stating whether there were no patients found or too many patients (two or more) found.

Method (read):

GET [base]/Patient/[id]

Method (search):

GET/Patient

Example:

GET [base]/Patient/123
GET [base]/Patient

Optional search parameters:

This resource provides the coverage data that was effective as of the date of service of the claim.

Fetch and Search Criteria:

• GET [base]/Coverage/[id]
• Coverage:payor - GET [base]/Coverage?[parameter=value]&_include=Coverage:payor

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.

No records dated prior to 2016-01-01 will be returned.

Method (read):

GET [base]/ExplanationOfBenefit/[id]

Method (search):

GET [base]/ExplanationOfBenefit?

Optional search parameters:

Examples:

GET [base]/ExplanationOfBenefit/219

GET [base]/ExplanationOfBenefit?patient=[id]&_lastUpdated=gt2019

GET [base]/ExplanationOfBenefit?patient=[id]&type=|oral

Data that reflects an activity that is performed with or on a patient as part of the provision of care.

Returns procedure data back to, and including, 2016-01-01.

Method (read):

GET [base]/Procedure/[id]

Method (Search):

GET [base]/Procedure?patient=[id]

- patient is a required parameter

Optional search parameters:

Examples:

GET [base]/Procedure?patient=1291938

GET [base]/Procedure?patient=1137192&date=ge2019-01-14

Data that reflects an activity that is performed with or on a patient as part of the provision of care. Returns condition data back to, and including, 2016-01-01.

Method (read):

GET [base]/Condition/[id]

Method (Search):

GET [base]/Condition?patient=[id]

- patient is a required parameter

Optional search parameters:

Examples:

GET [base]/Condition?patient=1291938

Data that reflects a patient’s immunization history.

Returns immunization data back to, and including, 2016-01-01.

Method (read):

GET [base]/Immunization/[id]

Method (Search):

GET [base]/Immunization?patient=[id]

- patient is a required parameter

Optional search parameters:

Examples:

GET [base]/Immunization?patient=1291938

Data that reflects a patient’s laboratory test results.

Returns laboratory result observations back to, and including, 2016-01-01.

Method (read):

GET [base]/Observation/[id]

Method (Search):

GET [base]/Observation?patient=[id]

- patient is a required parameter

Optional search parameters:

Examples:

GET [base]/Observation?patient=[id]&category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory

GET [base]/Observation?patient=[id]&code={system|}[code]{,{system|}[code],...}

The process for registering production applications mimic our sandbox process above. It is highly recommended that you first register your application as a Sandbox application. Doing so will result in immediate access to mock data to test your application. Once your testing is complete, then you will need to re-register your application as a Production application.

Production application for use with Public Access APIs (formulary, provider directory and pharmacy directory) will be automatically approved. Production application requests for Patient Access APIs will require review from our security and compliance team prior to approving access. Our security and compliance team will reach out with any questions during this review process.

Approved production applications that will be used to access member data will need to support 4 separate launch URLs. UnitedHealthcare's interoperability APIs requires member authentication via their IDP (identity provider) prior to authorization.

As of our 6/8/2021 release the following payers within United Healthcare are supported for members to be able to share their data. Each of the payers below should be a choice for members. The subsequent launch URLs are as follows.

• Sierra Health and Life
• Rocky Mountain

Below are guidelines you should follow to be successful in your UnitedHealthcare interoperability API integration.

Your privacy policy

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

Member revokes access

A member may revoke access to your application via their member portal. When you encounter an invalid token indicating a member has revoked access, you should make a reasonable attempt to handle that case making it easy for the member to understand what is happening with their data.

To join the developer sandbox, register a sample application and retrieve synthetic data for a sample Patient ID by calling the API, follow these four steps:

Note: Only Google Chrome and mobile browsers are supported at this time

Step 1: Register a sample application by navigating to the UnitedHealthcare interoperability API interoperability API landing page and clicking the App Owner tile.

Screen shot of landing page below:

Step 2: Create an OneHealthcare ID. All users must create an OneHealthcare ID to access the App Owner portal.

Step 3: Create your profile (Note: you will only see this page once at initial login.)

Step 4: Register your organization (Note: This is a one-time process. On your next login you will default to a dashboard view of all applications).

Our security and compliance team will review your organization registration and approve or deny your ability to register applications.

Step 5: Upon approve or denial you will receive an email notification. If approved your will be able to log back into the App owner portal and begin registering applications.

Step 6: “Register New App” to register new application and choose sandbox as the environment (Note: Sandbox is only applicable for Patient Access apps or apps using both Patient access and Public access APIs).

Step 6.1: Obtain Client ID and Secret.

URL - https://sandbox.authz.flex.optum.com/

Base URL for Sandbox API calls https://sandbox.fhir.flex.optum.com/R4

To test out your sandbox application with the UnitedHealthcare interoperability API, you will need to create a test member account via OneHealthcare ID when prompted to login as part of the authentication/authorization process. Note: You can use the same OneHealthcare ID that was registered to access the vendor portal and register applications.

UnitedHealthcare will offer the following support consistent with stated government regulations and current operational guidelines.

General support hours are available Monday through Friday from 9:00 am to 4:00 pm CST. General support is not provided on holidays or weekends. General support hours apply to:

• Vendor registration (organization or application)
• The developer sandbox environment

UnitedHealthcare regularly monitors system operations and responsiveness. The system is expected to be operational 24 hours a day, 7 days a week and 365 days a year. System functionality support is available 24 hours a day, 7 days a week and 365 days a year for:

• Vendor API Call Receipts and Responses (Support Available every day)

The system will accept and respond to organizational and application registration submissions from third party application vendors as follows: