UnitedHealthcare Interoperability APIs
UnitedHealthcare Interoperability APIs are developer-friendly, standards-based APIs that enable third party application vendors to connect their application 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 provide the functionality listed below:
- Enable developers to register member-facing applications
- Enable members to provide consent for an application to access their data
- Use the HL7 Fast Healthcare Interoperability Resources (FHIR) standard for member data
- Use the OAuth 2.0 / Open ID Connect standard for member authorization
- Use the HL7 FHIR standard for sharing public non-member specific data
Release notes
To use the UnitedHealthcare interoperability APIs 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.
UnitedHealthcare also supports non-authenticated public directory endpoints. Please see core resources documentation section for further details.
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
Patient access
patient/Condition.read
patient/Coverage.read
patient/Encounter.read
patient/ExplanationOfBenefit.read
patient/Immunization.read
patient/MedicationDispense.read
patient/MedicationRequest.read
patient/Observation.read
patient/Patient.read
patient/Procedure.read
Public access
Provider directory
public/Organization.read
public/OrganizationAffiliation.read
public/Practitioner.read
public/PractitionerRole.read
public/Network.read
public/Endpoint.read
public/HealthcareService.read
public/InsurancePlan.read
public/Location.read
Pharmacy directory
public/HealthcareService.read
public/InsurancePlan.read
public/Location.read
public/Organization.read
public/OrganizationAffiliation.read
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. 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.
Multiple payers are available under UnitedHealthcare
Use this table to populate the [payer] annotations in any URL below.
| id | Description |
|---|---|
| hsid | UnitedHealthcare |
| sierra | Sierra Health and Life |
| rmhp | Rocky Mountain |
| healthx | People's Health |
| sandbox | Sandbox Testing Environment |
Native mobile application support
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:
code_verifier = random, non-guessable code
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”
URI protocol
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.
custom_uri:// protocol
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:
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_uri 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 | Provided upon client application approval. |
| scope | Space separated list of requested scopes.
|
| state | A random string generated by the client which will be sent back from AuthZ to verify authenticity. |
| redirect_uri | The URI that the OAuth code request returns the user to. |
| code_challenge (if using PKCE) |
Client generated random string that is SHA256 hashed and then BASE64 encoded. (See info box below) |
| code_challenge_method (if using PKCE) |
S256 |
Code challenge generation
- 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.
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
Example 2 GET Request (if not using PKCE)
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
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 |
|---|---|
| client_id | The client id provided during application approval. |
| client_secret (if not using PKCE) | The client secret provided during application approval. |
| code | The code returned in the redirect. |
| code_verifier (if using PKCE) | The original random string that was used for the code_challenge parameter in the code request. Do not SHA256 hash it or Base64UrlEncode it. |
| grant_type | authorization_code |
| redirect_uri | The same redirect URI sent in the code request. |
Sample token request
POST /oauth/token HTTP/1.1
Host: https://sandbox.authz.flex.optum.com
Content-Type: application/x-www-form-urlencoded
(If using PKCE)
grant_type=authorization_code&code=AUTH_CODE_HERE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&code_verifier=CODE_VERIFIER
- or (If NOT using PKCE) -
grant_type=authorization_code&code=AUTH_CODE_HERE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&client_secret=CLIENT_SECRET
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. |
| patient | The patient identifier used for FHIR requests |
Sample token response
{
"access_token": "RsT5OjbzRn430zqMLgV3Ia",
“patient”: ”2234234234”
"expires_in": 3600,
"scope": "patient/patient.read",
"refresh_token": "PiV5OjbzRn520zwCJwV3Ia"
}
Client credentials (system-to-system) and Authenticated 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 401 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:
POST /oauth/token HTTP/1.1
Host: https://[payer].authz.flex.optum.com
grant_type=refresh_token&refresh_token=xxxxxxxxxxx&client_id=CLIENT_ID&client_secret=CLIENT_SECRET
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
Versions
| Source | IG Version | FHIR Version |
|---|---|---|
| US Core Implementation Guide | 3.2 | 4.01 |
| CARIN Implementation Guide for Blue Button | 1.1.0 | 4.01 |
| DaVinci Payer Data Exchange (PDEX) | 1.0.0 | 4.01 |
| DaVinci PDEX Plan Net | 1.0.0 | 4.01 |
| DaVinci PDEX US Drug Formulary | 1.0.1 | 4.01 |
Note: The following tool can be used for validation
Version Histories
Below are links to the IG histories for each source listed in the table above
- US Core Implementation Guide: http://hl7.org/fhir/us/core/history.html
- CARIN Implementation Guide for Blue Button: http://hl7.org/fhir/us/carin-bb/history.html
- DaVinci Payer Data Exchange (PDEX): http://hl7.org/fhir/us/davinci-pdex/history.html
- DaVinci PDEX Plan Net: http://hl7.org/fhir/us/davinci-pdex-plan-net/history.html
- DaVinci PDEX US Drug Formulary: http://hl7.org/fhir/us/davinci-drug-formulary/history.html
Authorization Required Endpoints
Authorization documentation is located in the application owner portal. This information is shared after successful organization registration and approval. Please login and register your organization to view this information.
Authorization NOT Required Endpoints
- These endpoints are only applicable to the public directory API calls
Base request URL
https://public.fhir.flex.optum.com/R4
Metadata capability statement
https://public.fhir.flex.optum.com/R4/metadata
Note: UnitedHealthcare also supports both authenticated and non-authenticated public directory endpoints.
Healthcare Service [DaVinci 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?service-category=prov
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 |
| characteristic | Token |
| coverage-area | String |
| location.address | String |
| location.address-city | String |
| location.address-postalcode | String |
| location.address-state | String |
Examples:
GET [base]/HealthcareService?service-category=prov&name=Stewart
GET [base]/HealthcareService?service-category=prov&name=Stewart&specialty=207R00000X
Insurance Plan [DaVinci 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 |
| owned-by | Reference (organization) |
| plan-type | Token |
| type | Token |
Examples:
GET [base]/InsurancePlan?name=AARP
GET [base]/InsurancePlan?type=mediadv
GET [base]/InsurancePlan?coverage-area=17d3a57ef4bce23a2ea4da87259a7934e99b539
Location [DaVinci 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) |
| partof | Reference (Location) |
| type | Token |
| address-city | String |
| address-state | String |
| address-postalcode | String |
| address-country | String |
Examples:
GET [base]/Location?address=Orlando
GET [base]/Location?address-state=CA
GET [base]/Location?address-postalcode=97035-2591
Organization [DaVinci 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 |
| partof | Reference (organization) |
| profile | String |
| address-city | String |
| address-state | String |
| address-postalcode | String |
| identifier | String |
| type | String |
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
Network [DaVinci 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 |
| partof | Reference (organization) |
| profile | String |
| address-city | String |
| address-state | String |
| address-postalcode | String |
| identifier | String |
| type | String |
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
Organization Affiliation [DaVinci 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?role=provider
Note: role is required parameter for 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 |
| location.address | String |
| location.address-city | String |
| location.address-state | String |
| location.address-postalcode | String |
Examples:
GET [base]/OrganizationAffiliation?specialty=230000000X& role=provider
GET [base]/OrganizationAffiliation?location.address-city=Orlando& role=provider
Practitioner [DaVinci 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 |
| identifier | String |
| address-state | String |
| qualification-wherevalid-code | String |
Examples:
GET [base]/Practitioner?name=dice
GET [base]/Practitioner?given=slice
GET [base]/Practitioner?address-state=CA
GET [base]/Practitioner?identifier=123456
Practitioner Role [DaVinci 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 |
| location.address | String |
| location.address-city | String |
| location.address-postalcode | String |
| location.address-state | String |
Examples:
GET [base]/PractitionerRole?specialty=340000000X
GET [base]/PractitionerRole?location.address-state =CA
Note: UnitedHealthcare also supports both authenticated and non-authenticated public directory endpoints.
Pharmacy Healthcare Service [DaVinci PDEX Plan Net]
The Healthcare Service resource typically describes services offered by a Pharmacy or Pharmacy Organization. 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.
The Healthcare Service resource typically describes services, or specialties value set based on National Uniform Claim Committee (NUCC) Health Care Provider Taxonomy code set.
Method (read):
GET [base]/HealthcareService/[id]
Method (search):
GET [base]/HealthcareService?service-category=pharm&coverage-area=90210
Search parameters:
| Name | Type | Required/Optional |
|---|---|---|
| _id | Token | |
Type |
String |
Required |
name |
String |
Optional |
location |
Reference (location) |
Optional |
organization |
Reference (organization) |
Optional |
coverage-area |
String |
Required |
specialty |
Token |
Optional |
service-category |
StringDt |
Required |
_count |
String |
Optional |
getpagesoffset |
String |
Optional |
Examples:
GET [base]/HealthcareService?service-category=pharm&coverage-area=90210
GET [base]/HealthcareService?service-category=pharm&coverage-area=90210&specialty=3336C0003X&specialty=3336H0001X&specialty=332800000X
Pharmacy Insurance Plan [DaVinci 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 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).
Pharmacy API provides Health insurance plan information provided under the Federal Medicare program covering prescription drugs i.e. Medicare Part D Plans.
Method (read):
GET [base]/InsurancePlan/[id]
Method (search):
GET [base]/InsurancePlan?type=medid
Search parameters
Name |
Type |
Required/Optional |
_id |
Token |
Optional |
name |
String |
Optional |
type |
StringDt |
Required |
address-postalcode |
String |
Required |
_count |
String |
Optional |
getpagesoffset |
String |
Optional |
Examples:
GET [base]/InsurancePlan? type= medid & address-postalcode= 92629&Name= AARP Medicare Advantage Choice Plan 1 (PPO)
GET [base]/InsurancePlan? type= medid
Pharmacy Location Service [DaVinci PDEX Plan Net]
Location instances provide information about location where pharmacy service is provided, including contact information, address, accessibility, hours of operation and contact, as well as position (latitude and longitude).
Location gives is the demographic information about a particular pharmacy covering the details like address and contact information.
Method (read):
GET [base]/Location/[id]
Method (search):
GET [base]/Location?type=pharm
Search parameters:
Name |
Type |
Required/Optional |
type |
Token |
Required |
address-postalcode |
String |
Required |
_count |
String |
Optional |
getpagesoffset |
String |
Optional |
Examples:
GET [base]/Location?type=pharm&address-postalcode=90210
Pharmacy Organization Service [DaVinci 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 (read):
GET [base]/Organization/[id]
Method (search):
GET [base]/Organization?type=phar
Search parameters:
Name |
Type |
Required/Optional |
_id |
Token |
Optional |
Type |
String |
Required |
name |
String |
Optional |
address-postalcode |
String |
Required |
_count |
String |
Optional |
getpagesoffset |
String |
Optional |
Examples:
GET [base]/Organization? type=phar&address-postalcode=90210
GET [base]/Organization? type=phar&address-postalcode=90210 &name=RITE AID PHARMACY
Pharmacy Organization Affiliation [DaVinci PDEX Plan Net]
The Organization Affiliation resource describes relationships between two or more Pharmacy Organizations, it is an entity which provider services related to the storage, compounding, dispensing and sale of drugs.
Pharmacy Organization Affiliation API provides information about location(s) where pharmacy provide services, the availability of those services, electronic endpoints, and other relevant information.
Method (read):
GET [base]/ OrganizationAffiliation/[id]
Method (search):
GET [base]/OrganizationAffiliation?role=pharmacy
Search parameters:
Name |
Type |
Required/Optional |
_id |
Token |
Optional |
role |
String |
Required |
location |
Reference (location) |
Optional |
service |
Reference (healthcareservice) |
Optional |
_count |
String |
Optional |
getpagesoffset |
String |
Optional |
address-postalcode |
String |
Required |
identifier (contractId, segmentId, pbpNumber) |
StringAndListParam |
Optional |
Examples:
GET [base]/OrganizationAffiliation?role=pharmacy&address-postalcode=90210&identifier=segmentId-000&identifier=pbpNumber-001&identifier=contractId-H0543
GET [base]/OrganizationAffiliation?identifier=segmentId-000&identifier=pbpNumber-001&identifier=contractId-H0543&address-postalcode=90210&_count=2&_getpagesoffset=2&role=pharmacy
Patient [CARIN BB]
Demographics and other administrative information about an individual or animal receiving care or other health-related services.
Method (read):
GET [base]/Patient/[id]
Method (search):
GET/Patient
Example:
GET [base]/Patient/123
GET [base]/Patient
Optional search parameters:
| Name | Type |
|---|---|
| _id | Token |
| _count | Positive integer |
| gender | Token |
| identifier | Token |
| name | String |
| birthdate | Date Range |
Coverage [CARIN BB]
This resource provides the coverage data that was effective as of the date of service of the claim.
Method (read):
GET [base]/Coverage/[id]
Method (search):
GET/Coverage
Example:
GET [base]/Coverage/123
GET [base]/Coverage
| Name | Type |
|---|---|
| _id | Token |
| _count | Positive integer |
| patient | Token |
Explanation of Benefit (Institutional, Professional and Pharmacy) [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.
Returns records dated back to 2016-01-01, inclusive.
Method (read):
GET [base]/ExplanationOfBenefit/[id]
Method (search):
GET [base]/ExplanationOfBenefit
POST [base]/ExplanationOfBenefit/_search
Optional search parameters:
| Name | Type |
|---|---|
| _id | Token |
| _count | Positive integer |
| _lastUpdated | Date range |
| identifier | Token |
| service-date | Date range |
| type | Token |
| patient | Token |
Examples:
GET [base]/ExplanationOfBenefit/219
GET [base]/ExplanationOfBenefit?patient=[id]&_lastUpdated=gt2019
GET [base]/ExplanationOfBenefit?patient=[id]&type=|professional
Note: Current EOB types Institutional, Professional and Pharmacy are supported by CARIN BB 1.1. Oral and vision will be supported in CARIN BB 2.0.
Condition [USCDI 2.0/US Core]
A clinical condition, problem, diagnosis, or other event, situation, issue, or clinical concept that has risen to a level of concern.
Returns condition data back to 2016-01-01, inclusive.
Method (read):
GET [base]/Condition/[id]
Method (Search):
GET [base]/Condition
POST [base]/Condition/_search
Optional search parameters:
| Name | Type |
|---|---|
| _id | Token |
| _count | Positive integer |
| _lastUpdated | Date range |
| _revinclude | (limited to “Provenance:target”) |
| patient | Token |
| onset-date | Date Range |
Examples:
GET [base]/Condition?patient=1291938
Encounter [USCDI 2.0/US Core]
An interaction between a patient and healthcare provider(s) for the purpose of providing healthcare service(s) or assessing the health status of a patient.
Returns encounter history data back to, and including, 2016-01-01.
Method (read):
GET [base]/Encounter/[id]
Method (Search):`
GET [base]/Encounter
POST [base]/Encounter/_search
Optional search parameters:
| Name | Type |
|---|---|
| _id | Token |
| _count | Positive integer |
| _revinclude | (limited to “Provenance:target”) |
| date | Date Range |
| patient | Token |
Examples:
GET [base]/Encounter?patient=1291938
GET [base]/Encounter?date=gt2021-01-01
Immunization [USCDI 2.0/US Core]
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
POST [base]/Immunization/_search
Optional search parameters:
| Name | Type |
|---|---|
| _id | Token |
| _count | Positive integer |
| _revinclude | (limited to “Provenance:target”) |
| date | Date Range |
| patient | Token |
| status | Token |
Examples:
GET [base]/Immunization?patient=1291938
Medication Dispense [USCDI 2.0/US Core]
Data that represents medication products to be or has been dispensed for a patient.
Returns medication history data back to, and including, 2016-01-01.
Method (read):
GET [base]/MedicationDispense/[id]
Method (Search):
GET [base]/MedicationDispense
POST [base]/MedicationDispense/_search
Optional search parameters:
| Name | Type |
|---|---|
| _id | Token |
| _count | Positive integer |
| _revinclude | (limited to “Provenance:target”) |
| _lastUpdated | Date Range |
| patient | Token |
Examples:
GET [base]/MedicationDispense?patient=1291938
GET [base]/MedicationDispense?_lastUpdated=gt2021-01-01
Medication Request [USCDI 2.0/US Core]
Data that reflects a patient’s prescribed medication history.
Returns medication history data back to, and including, 2016-01-01.
Method (read):
GET [base]/MedicationRequest/[id]
Method (Search):
GET [base]/MedicationRequest
POST [base]/MedicationRequest/_search
Optional search parameters:
| Name | Type |
|---|---|
| _id | Token Or List |
| _count | Positive integer |
| _lastUpdated | Date range |
| _revinclude | (limited to “Provenance:target”) |
| authoredon | Date Range |
| patient | Token |
| intent | Token Or List |
| status | Token Or List |
Examples:
GET [base]/MedicationRequest?patient=1291938
GET [base]/MedicationRequest?patient=1291938&intent=filler-order
GET [base]/MedicationRequest?patient=1291938&intent=filler-order,plan&status=active
Observation Laboratory Result and Vitals [USCDI 2.0/US Core]
Measurements and simple assertions made about a patient including laboratory test results and vital signs.
Returns observations back to 2016-01-01, inclusive.
Method (read):
GET [base]/Observation/[id]
Method (Search):
GET [base]/Observation
POST [base]/Observation/_search
Optional search parameters:
| Name | Type |
|---|---|
| _id | Token |
| _count | Positive integer |
| _revinclude | (limited to “Provenance:target”) |
| category | Token |
| code | Token |
| date | Date Range |
| patient | Token |
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],...}
Patient [USCDI/US Core]
Demographics and other administrative information about an individual or animal receiving care or other health-related services.
Method (read):
GET [base]/Patient/[id]
Method (search):
GET/Patient
Example:
GET [base]/Patient/123
GET [base]/Patient
Optional search parameters:
| Name | Type |
|---|---|
| _id | Token |
| _count | Positive integer |
| gender | Token |
| identifier | Token |
| name | String |
| birthdate | Date Range |
Procedure [USCDI 2.0/US Core]
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
POST [base]/Procedure/_search
Optional search parameters:
| Name | Type |
|---|---|
| _id | Token |
| _count | Positive Integer |
| _lastUpdated | Date range |
| _revinclude | (limited to “Provenance:target”) |
| code | Token |
| status | Token |
| date | Date range |
| patient | Token |
Examples:
GET [base]/Procedure?patient=1291938
GET [base]/Procedure?patient=1137192&date=ge2019-01-14
Coverage Plan [DaVinci PDEX Drug Formulary]
Coverage Plan describes details about the health plan which contains links to administrative information, a list of formulary drugs covered under that plan, and a definition of drug tiers and their associated cost-sharing models.
Method (search):
GET [base]/List
Optional search parameters:
| Name | Type |
|---|---|
| _id | String |
| _profile | String |
| identifier | String |
Examples:
GET [base]//List?_profile=http://hl7.org/fhir/us/Davinci-drug-formulary/StructureDefinition/usdf-CoveragePlan
Formulary Drug [DaVinci PDEX Drug Formulary]
Formulary Drug contains Drug information which is part of a formulary plan. Since UHC FLEX, supports the MemberSearch use case for Formulary Drug, the user is expected to pass in the drug plan information in order to get the drug formulary details. To note: The code values and descriptions are a combination of RXCUI and NDC (in cases of multiple coverage), and therefore the resource ID also prefixed with R or N respectively.
Method (search):
GET [base]/ MedicationKnowledge?_DrugPlan=e8e60bdd29fb1e6d7039c6c927ed4b692f25a6502022cb06661f9d21348b5600
Optional search parameters:
| Name | Type |
|---|---|
| DrugName | String |
| DrugTier | String |
| DrugPlan | String |
| Code | String |
| _id | String |
| _profile | String |
Examples:
GET [base]/ MedicationKnowledge?_profile=http://hl7.org/fhir/us/Davinci-drug-formulary/StructureDefinition/usdf-FormularyDrug&DrugPlan=[PlanID]
GET [base]/ MedicationKnowledge?_profile=http://hl7.org/fhir/us/Davinci-drug-formulary/StructureDefinition/usdf-FormularyDrug&DrugTier=NON-FORMULARY&DrugPlan= [PlanID]
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
Authorization server launch URL documentation is located in the application owner portal. This information is shared after successful organization registration and approval. Please login and register your organization to view this information.
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 you 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
General support hours (Business Hours) are available Monday through Friday from 9am CST to 4pm CST. Support is not provided on holidays or weekends. Support hours apply to:
- Vendor Registration (organization and application)
- Patient Sandbox
- Production (isolated and system wide)
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. UnitedHealthcare will make every effort to ensure system availability. In the event of a system response issue, restoration efforts will begin on the next business day.
Registration and response times
Registration and authentication is not required for public end points.
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 technical issues, use the support tab in the FLEX Vendor Admin Portal to submit a request for assistance.
For any assistance with portal registration, please contact flexvendorsupport@optum.com.
Technical support is not available for non-registered public directories. To provide feedback, please email to flexvendorsupport@optum.com.
