The Optum Real APIs for Medical Providers Technical Reference Guide will contain all of the essential information the user will need to integrate with an API and serve as a ready reference source should you encounter a problem.

Note: This guide is intended to be referenced by information technology personnel.

The Optum Real Pre-Service Eligibility API uses JavaScript Object Notation (JSON) for requests and responses. All API traffic is encrypted over HTTPS and authentication is handled with OAuth2. 

The Real Pre-Service Eligibility API provides pre-service member eligibility information via a GraphQL endpoint.

Query Parameters: GET_ELIGIBILITY

Test API in sandbox or in production:

1. Use token generated using client ID and secret key for sandbox or production.
2. Download API specs from overview page - every API overview section provides links to download the file in a JSON format, which generates our documentation for developers to use.
3. Hit API endpoint through the following options:

• Use Try It page to request complete API response or customize response.
  OR
• Use Postman to request complete API response or customize response.
  API endpoint:

HTTP response codes

Notes:
DO NOT perform load testing or production data testing in the sandbox environment. Please use the sandbox ONLY to view sample API responses to HTTP requests using our predefined values and to familiarize yourself with our APIs.

To perform load testing and production data testing, we recommend using our APIs in the production environment.

Request Elements:

Response Elements:

Example

{
"query": "query CheckEligibility($input: EligibilityInput!) { checkEligibility(input: $input) { eligibility { eligibilityInfo { member { memberId firstName lastName middleName suffix dateOfBirth gender relationshipCode dependentSequenceNumber individualRelationship { code description } relationshipType { code description } } contact { addresses { type street1 street2 city state country zip zip4 } } insuranceInfo { policyNumber eligibilityStartDate eligibilityEndDate planStartDate planEndDate policyStatus planTypeDescription groupName address { type street1 street2 city state country zip zip4 } stateOfIssueCode productType productId productCode payerId lineOfBusinessCode governmentProgramCode coverageType insuranceTypeCode insuranceType } associatedIds { alternateId medicaidRecipientId exchangeMemberId alternateSubscriberId hicNumber mbiNumber subscriberMemberFacingIdentifier survivingSpouseId subscriberId memberReplacementId legacyMemberId healthInsuranceExchangeId } planLevels { level family { networkStatus planAmount planAmountFrequency remainingAmount } individual { networkStatus planAmount planAmountFrequency remainingAmount } } delegatedInfo { entity payerId contact { phone fax email } addresses { type street1 street2 city state country zip zip4 } } } primaryCarePhysician { lastName firstName middleName phoneNumber address { type street1 street2 city state country zip zip4 } affiliateHospitalName providerGroupName pcpSpeciality pcpStartDate pcpEndDate providerNPI providerTIN acoNetworkDescription acoNetworkId } coordinationOfBenefits { coordinationOfBenefitDetails { member { id name } policy { policyNumber groupNumber coverageType insuranceTypeCode medicareEntitlementType medicareEntitlementReason effectiveDate terminationDate verificationDate } payer { name phoneNumber address { city country state street1 street2 zip zip4 type } } cobPrimacy { indicator description message } } primacyStatus { uhcPolicyNumber policyEffectiveDate policyTerminationDate primacy { indicator description message } } cobUpdateInformation { cobUpdateMessage cobLastVerifiedDate } disclaimer } idCardImages { side content contentType } providerNetwork { status tier speciality } serviceLevels { family { networkStatus services { service serviceCode serviceDate status planAmount remainingAmount metYearToDateAmount message { coPay { isSingleMessageDetail isViewDetail messages subMessages { service status copay msg startDate endDate minCopay minCopayMsg maxCopay maxCopayMsg isPrimaryIndicator exactCopay { coveredStatus copayDetails { amount serviceSetting } } isPrimaryIndicator } limitationInfo {lmtPeriod lmtType lmtOccurPerPeriod lmtDollarPerPeriod message } isMultipleCopaysFound } coInsurance { isSingleMessageDetail isViewDetail messages subMessages { service status copay msg startDate endDate minCopay minCopayMsg maxCopay maxCopayMsg isPrimaryIndicator } limitationInfo {lmtPeriod lmtType lmtOccurPerPeriod lmtDollarPerPeriod message } isMultipleCoinsuranceFound } deductible { isSingleMessageDetail isViewDetail messages subMessages { service status copay msg startDate endDate minCopay minCopayMsg maxCopay maxCopayMsg isPrimaryIndicator } limitationInfo {lmtPeriod lmtType lmtOccurPerPeriod lmtDollarPerPeriod message } } benefitsAllowed { isSingleMessageDetail isViewDetail messages subMessages { service status copay msg startDate endDate minCopay minCopayMsg maxCopay maxCopayMsg isPrimaryIndicator } limitationInfo {lmtPeriod lmtType lmtOccurPerPeriod lmtDollarPerPeriod message } } benefitsRemaining { isSingleMessageDetail isViewDetail messages subMessages { service status copay msg startDate endDate minCopay minCopayMsg maxCopay maxCopayMsg isPrimaryIndicator } limitationInfo {lmtPeriod lmtType lmtOccurPerPeriod lmtDollarPerPeriod message } } coPayList {placeOfService copay service startDate endDate messages} coInsuranceList {placeOfService coinsurancePercent service startDate endDate messages}} } } individual { networkStatus services { service serviceCode serviceDate status planAmount remainingAmount metYearToDateAmount message { coPay { isSingleMessageDetail isViewDetail messages subMessages { service status copay msg startDate endDate minCopay minCopayMsg maxCopay maxCopayMsg exactCopay { coveredStatus copayDetails { amount serviceSetting } } isPrimaryIndicator } limitationInfo {lmtPeriod lmtType lmtOccurPerPeriod lmtDollarPerPeriod message } isMultipleCopaysFound } coInsurance { isSingleMessageDetail isViewDetail messages subMessages { service status copay msg startDate endDate minCopay minCopayMsg maxCopay maxCopayMsg isPrimaryIndicator } limitationInfo {lmtPeriod lmtType lmtOccurPerPeriod lmtDollarPerPeriod message } isMultipleCoinsuranceFound } deductible { isSingleMessageDetail isViewDetail messages subMessages { service status copay msg startDate endDate minCopay minCopayMsg maxCopay maxCopayMsg isPrimaryIndicator } limitationInfo {lmtPeriod lmtType lmtOccurPerPeriod lmtDollarPerPeriod message } } benefitsAllowed { isSingleMessageDetail isViewDetail messages subMessages { service status copay msg startDate endDate minCopay minCopayMsg maxCopay maxCopayMsg isPrimaryIndicator } limitationInfo {lmtPeriod lmtType lmtOccurPerPeriod lmtDollarPerPeriod message } } benefitsRemaining { isSingleMessageDetail isViewDetail messages subMessages { service status copay msg startDate endDate minCopay minCopayMsg maxCopay maxCopayMsg isPrimaryIndicator } limitationInfo {lmtPeriod lmtType lmtOccurPerPeriod lmtDollarPerPeriod message } } coPayList {placeOfService copay service startDate endDate messages} coInsuranceList {placeOfService coinsurancePercent service startDate endDate messages} } } } } additionalInfo { fundingType businessSegment sizeDefinitionDescription revenueArrangementDescription hsa cdhp cmsHId cmsPackageBenefitPlanCode cmsSegmentId cmsContractId benefitPlanId virtualVisit designatedVirtualClinicNetwork medicaidVariableCode hraBalance hraMessage hraUnavailableMessage graceMessageByState gracePaidThrough gracePeriodMonth medicareGuidelines medicareEntitlementReason medicaidEntitlement { waiverLiabilityList { startDate endDate amount amountFrequency remainingAmount metYtdAmount } patientLiabilityList { startDate endDate amount amountFrequency remainingAmount metYtdAmount } transferOfPropertyPenaltyPeriod { startDate endDate } } } otherBeneficiaries { memberId firstName lastName middleName suffix dateOfBirth gender relationshipCode dependentSequenceNumber individualRelationship { code description } relationshipType { code description } } } } }",
"variables": {
"input": {
"memberId": "0012345678",
"firstName": "ABCD",
"lastName": "EFGH",
"dateOfBirth": "1959-05-30",
"serviceStartDate": "2025-05-13",
"serviceEndDate": "2025-05-13",
"coverageTypes": [
"Medical"
],
"payerId": "87726",
"providerLastName": "ST FRANCIS REGIONAL MEDICAL CENTER",
"providerFirstName": "",
"providerNPI": "123456789"
}
}
}

Sample Response

API health check:

The health check endpoint checks the operating status of our API. It is a ping for the API entry point to ensure the entry points are accessible. This is the first thing you can do if something goes wrong.

Performing the Optum Real APIs health check (for first-time users):

• To run the health check of an Optum Real API - the Real Pre Service Eligibility API, go to
  Healthcheck

Response If the API engine is working correctly and if the entry points are accessible, the API operating status response shows "OK."

NOTE

If you receive a response other than 200 OK, the health check failed.

Please submit a service ticket with Optum.