UnitedHealthcare Interoperability APIs
Developer-friendly, standards-based APIs that enable third party applications for vendors to connect their applications or programs to access UnitedHealthcare data.
Overview
UnitedHealthcare interoperability APIs enable UnitedHealthcare members to consent to have their data shared with third-party applications. It also allows third-party application owners to connect to provider and pharmacy directories, further referred to as “public non-member specific data.”
UnitedHealthcare Interoperability APIs:
- Enable developers to register member-facing applications
- Enable members to provide consent for an application to access their data
- Use the HL7 FHIR standard for member data and the OAuth 2.0 / Open ID Connect standard for member authorization
- Use the HL7 FHIR standard for sharing public non-member specific data
To use the UnitedHealthcare interoperability API OAuth 2 a developer must register their application. An organization must register as a user by creating an Optum 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 is available.
Access tokens have scopes, which define permissions and the resources 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. The following scopes are available for the following types of requests:
Note: Any Scope not currently listed is not supported
Patient access
patient/Patient.read
patient/ExplanationOfBenefit.read
patient/Procedure.read
The scopes and subsequent endpoints will only be supported for sandbox applications in the current release
Public access
Provider directory
user/Practitioner.read
user/PractitionerRole.read
user/Organization.read
user/OrganizationAffiliation.read
user/Network.read
user/Location.read
user/InsurancePlan.read
user/HealthcareService.read
This gives access to the correct FHIR (Fast Healthcare Interoperability Resources) Endpoints.
Our OAuth2 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 to function, 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 when a member reaches the authorization screen will be to share the scopes included in the initial request with your application. If a member makes a selection as to whether or not they want to share a type of data with your application and later decides they want to change that selection, they’ll need to be taken through the authorization flow again to make a different choice from the OAuth2 screen.
It is important to explain to members why you need certain data
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.
Native mobile application support
Public clients, such as native mobile application support follows the RFC 8252 - OAuth 2.0 for native applications authentication flow utilizing the PKCE extension and enables a custom URI scheme redirect.
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:
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(codeverifier)))
The following additional parameters and values are sent as part of the OAuth2.0 Authorization Request:
- code_challenge
- codechallengemethod = “S256”
URL protocol
The redirect_uri supports any URI protocol. See examples below:
- https:// protocol
- custom_url:// 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.
custom_url:// protocol
The custom_url 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_url should follow this format:
Top-level.domain(TLD).domain-name[.sub-domain][.app_name]
For example, if the UnitedHealthcare interoperability API team created an application we might create a custom_url of:
api.uhc.com
This would then be incorporated into a redirect URI entry. Here is an example:
api.uhc.com&state=8e896a59f0744a8e93bf2f1f13230be5
The following query parameters are required:
| Response_type | Code |
|---|---|
| client_id | Dynamic value Provided upon client application approval. |
| scope | Dynamic value
|
| state | Dynamic value A random string generated by the client which will be sent back from AuthZ to verify authenticity. |
| redirect_uri | Dynamic value The URI that the OAuth code request returns the user to. |
| code_challenge | Dynamic value Client generated random string that is SHA256 hashed and then BASE64 encoded. (See info box below) |
| code_challenge_method | S256 |
Code challenge generation
Create a random:
string: eae64b84b53f479d92ab81dce7c8bbe608492951def502d84b4f0cd7
Create the SHA256 hash, then base64-encode the string:
hI2vVv0Er_dHX9lUJo2O8lbFzkxfChVyM2WcHfODLnU
Use the base64 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:
| Parameter name | Parameter value |
|---|---|
| grant_type | authorization_code |
| code | Dynamic value The code returned in the redirect. |
| redirect_uri | Dynamic value The same redirect URI sent in the code request. |
| client_id | Dynamic value The client id provided during application approval. |
| code_verifier | Dynamic value The original random string that was used for the code_challenge parameter in the code request. Do not SHA256 hash it or base64 encode it. |
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&code_verifier=CODE_VERIFIER
The POST response will return a JSON object with the following properties:
| access_token | The access token used for data requests. |
| refresh_token | Used to request new access tokens. |
| expires_in | The expiration time of the access token. |
| scope | The scope values the token supports. |
Sample token response
{
"access_token":"RsT5OjbzRn430zqMLgV3Ia",
“patient”:”2234234234”
"expires_in":3600,
"scope": "patient/patient.read",
"refresh_token": "PiV5OjbzRn520zwCJwV3Ia"
}
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.
POST /oauth/token HTTP/1.1
Host: https://[payer].authz.flex.optum.com
grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&scope=user/Practitioner.read%20user/PractitionerRole.read
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, a POST 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:
POST /oauth/token HTTP/1.1
Host: https://[payer].authz.flex.optum.com
grant_type=refresh_token&refresh_token=xxxxxxxxxxx
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:
Example request
curl -H "Authorization: Bearer AeT4OkbzMr288gJ2ag9Fwe" https://payer.fhir.flex.optum.com/formulary
Base request URL
https://[payer].fhir.flex.optum.com/R4
Where [payer] is one of the following:
rmhp – Rocky Mountain
sierra – Sierra health and life
hsid – United healthcare
healthx – Peoples Health
Metadata capability statement
https://[payer].fhir.flex.optum.com/R4/metadata
Well known URL
https://[payer].fhir.flex.optum.com/R4/.well-known/smart-configuration
Non-member specific (available in current release)
PDEX Plan net specific resources
Healthcare Service [PDEX Plan net]
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
Optional search parameters:
| Name | Type |
|---|---|
| _id | Token |
| endpoint | Reference (endpoint) |
| location | Reference (location) |
| name | String |
| organization | Reference (organization) |
| service-category | Token |
| service-type | Token |
| specialty | Token |
Examples:
GET [base]/HealthcareService?name=LabOne GET [base]/HealthcareService?specialty= http://loinc.org|99999-9 GET [base]/HealthcareService?name=LabOne&specialty=99999-9
Insurance Plan [PDEX Plan net]
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:
| Name | Type |
|---|---|
| _id | Token |
| administered-by | Reference (organization) |
| coverage-area | Reference (location) |
| name | String |
| network | Reference (organization) |
| owned-by | Reference (organization) |
| plan-coverage-area | Reference (location) |
| plan-type | Token |
| type | Token |
Examples:
GET [base]/InsurancePlan?name=GreenEarthGoldPPO GET [base]/InsurancePlan?type=|CommercialPPO GET [base]/InsurancePlan?coverage-area.address=Walla Walla
Location [PDEX Plan net]
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:
| Name | Type |
|---|---|
| _id | Token |
| address | String |
| organization | Reference (organization) |
| part of | Reference (organization) |
| type | Token |
Examples:
GET [base]/Location?address=Springfield
GET [base]/Location?type=|HOSP
GET [base]/Location?type=|OUTPHARM
Organization [PDEX Plan net]
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:
| Name | Type |
|---|---|
| _id | Token |
| address | String |
| endpoint | Reference (endpoint) |
| name | String |
| part of | Reference (organization) |
Examples:
GET [base]/Organization?address=Bahama
GET [base]/Organization?partof.name=AtlantisMed
Network [PDEX Plan net]
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:
| Name | Type |
|---|---|
| _id | Token |
| address | String |
| endpoint | Reference (endpoint) |
| name | String |
| part of | Reference (organization) |
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.name=AtlantisMed
Organization Affiliation [PDEX Plan net]
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:
| Name | Type |
|---|---|
| _id | Token |
| location | Reference (location) |
| network | Reference (organization) |
| participating-organization | Reference (organization) |
| primary-organization | Reference (organization) |
| role (code) | Token |
| service | Reference (healthcare service) |
| specialty | Token |
Examples:
GET [base]/OrganizationAffiliation?specialty=|230000000X
GET [base]/OrganizationAffiliation?location.name=UrgentCare
Practitioner [PDEX Plan net]
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:
| Name | Type |
|---|---|
| _id | Token |
| family | String |
| given | String |
| name | String |
Examples:
GET [base]/Practitioner?name=dice
GET [base]/Practitioner?given=slice
Practitioner Role [PDEX Plan net]
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:
| Name | Type |
|---|---|
| _id | Token |
| endpoint | Reference (endpoint) |
| location | Reference (location) |
| network | Reference (organization) |
| organization | Reference (organization) |
| practitioner | Reference (practitioner) |
| Role (code) | Token |
| service | Reference (healthcare service) |
| specialty | Token |
Examples:
GET [base]/PractitionerRole?specialty=|340000000X
GET [base]/PractitionerRole?location.name=UrgentCare
Member specific (not available in production current release: will be available for sandbox data)
Patient [CARIN BB]
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 ($match):
POST /Patient/$match
Example:
GET [base]/Patient/123 POST [base]/Patient/$match
-with body [bold attributes are required]
{
"resourceType": "Parameters",
"id": "example",
"parameter": [
{
"name": "resource",
"resource": {
"resourceType": "Patient",
"identifier": [
{
"use": "usual",
"type": {
"coding": [
{
"system": "http://hl7.org/fhir/v2/0203",
"code": "MR"
}
]
},
"system": "[Member ID System]",
"value": "[Member ID]"
}
],
"name": [
{
"family": "[family name]",
"given": [
"[given name]"
]
}
],
"gender": "[gender]",
"birthDate": "[YYYY-MM-DD]",
"address": {
"postalCode": "[postalCode]"
}
}
}
]
}
Explanation of Benefit [CARIN BB]
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?patient=[id] -patient is a required parameter
Optional search parameters:
| Name | Type |
|---|---|
| _id | Token |
| _lastUpdated | Date range |
| identifier | Token |
| service-date | Date range |
| type | Token |
Examples:
GET [base]/ExplanationOfBenefit/219
GET [base]/ExplanationOfBenefit?patient=[id]&_lastUpdated=gt2019
GET [base]/ExplanationOfBenefit?patient=[id]&type=|oral
Procedure [CARIN BB]
Data that reflect a payer’s coverage that was effective as of the date of service or the date of admission of the claim will be added to the Coverage Profile overview.
No records dated prior to 2016-01-01 will be returned.
Method (read):
GET [base]/Procedure?patient=[id]
-patient is a required parameter
Optional search parameters:
| Name | Type |
|---|---|
| _id | Token |
Examples:
GET [base]/Procedure?patient=1291938
GET [base]/Procedure?patient=1137192&date=ge2019-01-14
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.
Patient access authentication launch URLs
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.
Each of the payers below should be a choice for members. The subsequent launch URLs are as follows.
An example of how this data may be surfaced is below:
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:
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 Optum ID. All users must create an Optum 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.
To test out your sandbox application with the UnitedHealthcare interoperability API, you will need to utilize test member information as part of your request. Test Member Accounts.
Note: Please use Rocky or Sierra launch
URL - https://sandbox.authz.flex.optum.com/
The first user is sandbox1@testoptum.com with password Sandbox#1
Security questions:
- What is favorite color? black
- What is name of your first pet? dog
- What is your favorite sports team? panthers
The second user is sandbox2@testoptum.com with password Sandbox#2
Security questions:
- What is favorite color? black
- What is name of your first pet? dog
- What is your favorite sports team? panthers
The third user is sandbox3@testoptum.com with password Sandbox#3
Security questions:
- What is favorite color? black
- What is name of your first pet? dog
- What is your favorite sports team? panthers
Base URL for Sandbox API calls https://sandbox.fhir.flex.optum.com/R4
UnitedHealthcare will offer the following support consistent with stated government regulations and current operational guidelines.
General support hours
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
System monitoring
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)
Registration and response times
The system will accept and respond to organizational and application registration submissions from third party application vendors as follows:
| Registration type | Estimated response time1 |
|---|---|
New Organization Registration |
5 business days |
New Application Registration (Public Access) |
No approval required |
New Application Registration (Patient Access) |
5 business days |
Determination Appeals |
5 business days from receipt of request |
| Support request | Estimated response time1 |
|---|---|
Developer Sandbox Support Request |
48 business hours |
Vendor Production Support Request |
24 business hours |
| Data | Data feed timeframe |
|---|---|
Claims |
1 business day from adjudication |
Encounter data |
1 business day from receipt of encounter |
| Clinical data | 1 business day from receipt of data |
Provider directory |
30 calendar days of a payer receiving provider directory information OR an update to provider directory information |
Pharmacy directory |
30 calendar days of a payer receiving provider directory information OR an update to provider directory information |
For any question or concerns regarding registering your organization or application please contact flexvendorsupport@optum.com.
Disclaimers
- Response times do not include holidays or weekends.
- Longer timeframes may be expected in the case of a large-scale systemwide outage.