NOTE
Please use the table of contents on the right side of this page to quickly navigate to a desired section.
API Data dictionary
The following data dictionary includes all the essential information you will need to integrate with our Dental Pre-Care Eligibility Intelligence API and serves as a ready reference source should you encounter a problem. It is intended to support developers, analysts and stakeholders in understanding the structure, usage, and expected values of the data exchanged through the system.
Use this data dictionary:
- As a reference when integrating with or troubleshooting the API/data interface.
- Ensure all required fields are populated when constructing requests.
- Refer to HTTP status codes section for guidance on resolving issues.
Query examples — See the following example queries or API requests that illustrate the usage and expected formats; useful for developers and testers to understand expected formats and usage patterns.
Request body — Defines the input parameters required for API calls or data queries. Includes field names, data types, required/optional status, and descriptions.
Parameters — Provide required and optional fields for the API calls.
Response body — Lists the fields returned in the response payload. Includes field names, data types, formats, and descriptions.
NOTE
Please note that our APIs are private and secure, and require unique credentials to generate a Bearer token and gain access to. Please see (generate a Bearer token based on your API environment) to obtain access to our APIs.
URLs
| Sandbox | Production |
|---|---|
Generate Bearer token — https://sandbox-apigw.optum.com/apip/auth/sntl/v1/tokenHealth check — https://sandbox-apigw.optum.com/oihub/dnt/enh/eligibility/preservice/v1/healthcheckPre-Care Eligibility Intelligence — https://sandbox-apigw.optum.com/oihub/dnt/enh/eligibility/preservice/v1 | Generate Bearer token — https://apigw.optum.com/apip/auth/sntl/v1/tokenHealth check — https://sandbox-apigw.optum.com/oihub/dnt/enh/eligibility/preservice/v1/healthcheckPre-Care Eligibility Intelligence — https://apigw.optum.com/oihub/dnt/enh/eligibility/preservice/v1 |
Generate a Bearer token
Click Generate Bearer Token for Optum Real Dental APIs, for steps, see Generate a Bearer Token.
Pre-Care Eligibility Intelligence API OpenAPI Spec
To download, click Pre-Care Eligibility Intelligence API OpenAPI spec.
Perform API health check
The /healthcheck endpoint verifies that the connection to the API server is established and the API is operational. Use your Bearer token to perform API health check.
API TESTING/USING
- In our developer portal TryIt! interface
- You need to reapply the Bearer token within the Bearer token expiry span by entering it in the CREDENTIALS box to test/use different APIs.
- In your development platform
- The generated Bearer token need not be reapplied or re-entered to test/use different APIs; the same Bearer token will be used across all transactions during the full token lifespan, and you can automatically refresh the token just before it expires.
In the developer portal Try It! interface
- Paste the Bearer token (generated as mentioned in the preceding section) in the CREDENTIALS >> Bearer box as mentioned in the Generate a Bearer token section above.
- Click Try It! under the cURL Request box.
If the request was successful, the response shows such as, {"message": "Service is healthy"} in the RESPONSE box to indicate that the APIs are operational and are accessible. If the request failed, the reason shows in the RESPONSE box as listed in the HTTP Status Codes section at the end of this page or click the link in the TOC on the right.
Note that each API health message depends on the API being tested/used.
Reference: HTTP status codes
In your development platform
- Download our OpenAPI Spec (for example, to access a product OpenAPI spec you are using/testing, go to the required API Overview section >> click Download OpenAPI Spec.) and import it into the API project in your development platform.
- Expand the API collection folder and click the
Get Tokenendpoint to generate a Bearer token. - Click the
Bodytab and enter your unique secure credentials.grant_type: client_credentialsclient_id: your client_idclient_secret: your client_secret
- Send the request to generate a Bearer token.
- Now, click the
/healthcheckendpoint and send it view if the connection to the API server was established.
If the request was successful, the response shows such as, {"message": "Service is healthy"} in the RESPONSE box to indicate that the APIs are operational and are accessible. If the request failed, the reason shows in the RESPONSE box as listed in the HTTP Status Codes section at the end of this page or click the link in the TOC on the right.
Note that each API health message depends on the API being tested/used.
The Bearer token will be valid until the Bearer token expires to try the APIs.
Reference: HTTP Status Codes
Run Dental Pre-Care Eligibility Intelligence API
enh/eligibility/preservice/v1 (link to Dental Pre-Care Eligibility Intelligence API) — Retrieves the dental eligibility coverage details based on the parameters provided.
TIP
- Choose an option to test/use our APIs, that is, in our developer portal TryIt! interface (you need to copy and paste the unexpired Bearer token generated for testing the Healthcheck) and/or in your development platform.
- Repeat the steps provided in the Perform API Healthcheck >> In your developer platform or In our developer portal TryIt! interface section.
You can use the example field values provided in the Parameters table).
Parameters
| Parameter | In Developer Portal | In Development Platform | Description |
|---|---|---|---|
query | Enter the query field request data (example given below) | Click the Body to enter (see the following example) | GraphQL query for the Check Enhanced Dental Eligibility of a member (required) |
| variables | Expand (press the + symbol) the variables >> VARIABLES OBJECT >> input >> INPUT OBJECT to enter following parameters (Required) | ||
dateOfBirth | Enter/select the date of birth | Click the Body to enter (see the following example) | The date of birth of the member whose Enhanced Eligibility coverage is being checked (Required) |
firstName | Enter/select the first name | Click the Body to enter (see the following example) | Member's first name , for example, Muhammad (Required) |
lastName | Enter/select the last name | Click the Body to enter (see the following example) | Member's last name, for example, ATA (Required) |
memberId | Enter/select the member ID | Click the Body to enter (see the following example) | ID on the insurance ID card, for example, 042137147 (Required) |
payerId | Enter/select the payer ID | Click the Body to enter (see the following example) | Payer identifier; your 5-digit payer ID (required), example, 52133 |
providerFirstName | Enter the provider's first name | Click the Body to enter (see the following example) | Provider's first name (Optional) |
providerLastName | Enter the provider's last name | Click the Body to enter (see the following example) | Provider's last name (Optional) |
providerNPI | Enter the provider's NPI | Click the Body to enter (see the following example) | Provider's 10-digit NPI (Optional) |
serviceStartDate | Enter the service start date | Click the Body to enter (see the following example) | Eligibility coverage service start date (Optional) |
serviceEndDate | Enter the service end date | Click the Body to enter (see the following example) | Eligibility coverage service end date (Optional) |
CoverageTypes | Expand (press the + symbol) to add additional coverage type if needed | Click the Body to enter (see the following example) | For example, "Medical" (Optional) |
| Headers | |||
providerTaxId | Enter/select the provider's tax ID | Click the Params tab to add | Provider ID (example, 204868609) (Required) |
NOTE
Check the Headers and Body parameters to make sure that the values comply with the parameters provided in the Parameters table.
IMPORTANT
Please do not submit PHI or PII data on the developer portal's Try It! interface.
```json
{
"query": "query CheckEligibility($input: EligibilityInput!) { checkEligibility(input: $input) { eligibility { eligibilityInfo { trnId 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 } } } benefitNotes { result { benefitNotes { footNoteInfo { benefitSummaryType benefitSummaryDescription benefitSummarySequenceNumber benefitSummaryText } } } } benefitSummary { member { subscriberId employeeId groupId groupName groupPolicyNumber patientName { firstName lastName } memberSuffix memberEligibilityEffectiveDate eligibilityIndicator eligibilityTermDate productId { codeValue codeDesc } groupPlanEffectiveDate planYearBeginDate pcpIndicator claimAcceptingMonths carryOverMonth productPlanType productPlanTypeDescription productPlanTypeValueCode1 productPlanTypeValueCode1Description productPlanTypeValueCode2 productPlanTypeValueCode2Description tierIncentiveIndicator payorId claimsAddress } planLevelBenefits { providerType planLevelDeductibleInfo { deductibleAccumNumber deductibleAccumDesc deductibleNonEmbeddedInd memberDeductibleMaxAmt memberCarryoverAmt familyDeductibleMaxAmt familyCarryoverAmt deductibleCurrentYear currYearMemberDeductibleAmtSatisfied currYearFamilyDeductibleAmtSatisfied } planLevelLimitInfo { limitType { codeValue codeDesc } limitIndicator limitMemberAccumNumber limitMemberAccumDesc oopFamilyAccumNumber oopFamilyAccumDesc limitNonEmbeddedInd limitPeriod limitMemberMaxAmt oopFamilyMaxAmt limitCurrentYear currYearLimitMemberAmtSatisfied currYearOopFamilyAmtSatisfied limitPreviousYear prevYearOopMemberMaximumAmount prevYearOopFamilyMaximumAmount prevYearLimitMemberAmtSatisfied prevYearOopFamilyAmtSatisfied relatedCategory } } categoryLevelBenefits { providerType procedureCategory { codeValue codeDesc } coveredBenefits coveragePct memberCoinsurancePct copayAmt deductibleApplies waitingPeriodType waitingPeriod waitingPeriodMetDate deductibleType } } benefitUtilization { memberName { firstName middleName lastName } memberRelationship procedures { procedure { codeValue codeDesc } procedureCategory ehbIndicator inNetworkFrequency outOfNetworkFrequency ageLimit alternateBenefit serviceCount relatedCode services { serviceDate toothRange toothSurface procedureCode } } } } } }",
"variables": {
"input": {
"dateOfBirth": "1974-09-07",
"firstName": "MUHAMMAD",
"lastName": "ATA",
"memberId": "042137147",
"payerId": "52133",
"providerFirstName": "johnone",
"providerLastName": "doeone",
"providerNPI": "CABC",
"serviceStartDate": "2021-09-18",
"serviceEndDate": "2021-09-18",
"coverageTypes": [
"Dental"
]
}
}
}
```
Enter the information as mentioned in the preceding table and click TryIt! in the developer portal or click Send in your development platform.
IMPORTANT
Please note that the request requires you to provide all the required field values. Please note that these required values are GREYED out, which are pre-populated example values and can be selected to view the canned response. To view the required fields, expand the + symbol (indicated by the
variablesfield below.
```json
{
"data": {
"checkEligibility": {
"eligibility": [
{
"eligibilityInfo": {
"member": {
"memberId": "042137147",
"firstName": "MUHAMMAD",
"lastName": "ATA",
"dateOfBirth": "1974-09-07",
"gender": "M",
"individualRelationship": {
"code": "M",
"description": "Subscriber"
}
},
"insuranceInfo": {
"policyNumber": "0241816",
"eligibilityStartDate": "2021-09-01",
"eligibilityEndDate": "2199-12-31",
"planTypeDescription": "Preferred Provider Org.",
"groupName": "HOUSTON LIVESTOCK SHOW AND ROD",
"productType": "PPO",
"productId": "D0031356",
"payerId": "52133",
"insuranceType": "COMM"
}
},
"benefitNotes": {
"result": {
"benefitNotes": {
"footNoteInfo": [
{
"benefitSummaryType": "ACC",
"benefitSummaryDescription": "ACCIDENTAL COVERAGE",
"benefitSummaryText": "THERE IS NO SPECIAL COVERAGE FOR ACCIDENTAL CLAIMS. REFER TO MEDICAL FOR SPECIFIC QUESTIONS."
},
{
"benefitSummaryType": "CADD",
"benefitSummaryDescription": "CLAIMS ADDRESS",
"benefitSummaryText": "UNITED HEALTH CARE DENTAL CLAIMS PO BOX 30567 SALT LAKE CITY, UT 84130-0567"
}
]
}
}
},
"benefitSummary": {
"member": {
"subscriberId": "042137147",
"groupName": "HOUSTON LIVESTOCK SHOW AND ROD",
"productPlanType": "PPO"
},
"categoryLevelBenefits": [
{
"providerType": "I",
"procedureCategory": {
"codeValue": "01",
"codeDesc": "Diagnostic"
},
"coveredBenefits": "Y",
"coveragePct": "100"
},
{
"providerType": "I",
"procedureCategory": {
"codeValue": "10",
"codeDesc": "Crowns/Bridges"
},
"coveredBenefits": "Y",
"coveragePct": "60"
}
]
},
"benefitUtilization": {
"memberName": {
"firstName": "MUHAMMAD",
"lastName": "ATA"
},
"memberRelationship": "SUBSCRIBER",
"procedures": [
{
"procedure": {
"codeValue": "D0120",
"codeDesc": "periodic oral evaluation - established patient"
},
"procedureCategory": "01",
"inNetworkFrequency": "2 - F - 12M"
},
{
"procedure": {
"codeValue": "D1110",
"codeDesc": "prophylaxis - adult"
},
"procedureCategory": "02",
"inNetworkFrequency": "2 - F - 12M"
}
]
}
}
]
}
}
}
```
TIP
- Choose an option to test/use our APIs, that is, in our developer portal TryIt! interface (you need to copy and paste the unexpired Bearer token generated for testing the Healthcheck) and/or in your development platform.
- Repeat the steps provided in the Perform API Healthcheck >> In your developer platform or In our developer portal TryIt! interface section.
You can use the example field values provided in the Parameters table).
If the request failed, the reason shows in the response box. Here are the HTTP status codes.
API Setup
For information about, setting your API test environment, please see API Setup.
Subscribe to live and mock data testing in sandbox
Please see Subscribe to live and mock data testing in sandbox.
Integrate our APIs in production environment
Please see Integrate our APIs in production environment.
HTTP status codes
The following table provides error codes, including code values and error messages.
| HTTP Status Code | Description |
|---|---|
| 200 OK | Eligibility response successfully processed |
| 400 Bad Request | Invalid or missing request fields |
| 401 Unauthorized | Missing or invalid access token |
| 403 Forbidden | Token lacks required scopes |
| 500 Internal Server Error | Optum backend error |