Onboarding

Feature Enrollment

Work with the Enhanced Eligibility Support Team to enroll in the Value-Added Features that best aligns with your business needs. For more information on the available pre/post-Clearinghouse processing rules, please see the Value-Added Features section.

Authentication with Client Credentials

Authentication for the API utilizes OAuth Client Credentials flow. Please supply the onboarding team with an email to attach to your credentials. We can support user-based credentials or system-based credentials, where user-based refers to each discrete Developer or API Consumer has their own unique credentials, and system-based refers to a single set of credentials used by your Applications. Once credentials are created, they will be delivered via Secure email to the provided email address. See Getting Started for authenticating with the Enhanced Eligibility API and next steps.

Data Tenancy

Enhanced Eligibility is a multi-tenant solution, but you will only ever have access to your data. Every request requires the presence of an HTTP header called x-optum-tenant-id that specifies the ID of the tenant associated with your authentication token. This header is automatically applied via your unique credentials to enforce secure access to your data. If you provide this header yourself, it will automatically be stripped during authentication.

Existing Medical Network Customers

If you are an existing customer of the Medical Network Eligibility API, then you can opt-into our "Bring Your Own Key" feature. With this feature, Enhanced Eligibility will submit transactions to Medical Network using your existing credentials. By submitting with your credentials, you maintain your existing Provider enrollments and billing. Please work with the Enhanced Eligibility Support Team to configure this 'Bring Your Own Key' feature.

Eligibility Payer List

For the current payer list supported by Medical Network, please download the list supplied in the "IMN Real-Time Eligibility" section of this link. Use this document to find the "IMN Payer ID" to submit as the tradingPartnerServiceId on the Eligibility Request. If the specific payer requires enrollment, then please submit a support request to begin the enrollment process. To verify if enrollment is required, refer to "Enrollment Req'd" column.

If you are unable to send the "IMN Payer ID", please enroll in the Value-Added Feature "Payer Alias".

Coverage Discovery: Callback and Polling Options

Delivery Options

Coverage Discovery is a long-running asynchronous process. Customers enrolled in this capability must choose one of the following delivery models to receive completed task responses:


Option 1: Callback API (Recommended)

Customers may implement a callback API to receive responses automatically once a Coverage Discovery task is finalized. This is the recommended approach, especially for high-volume or high-traffic environments.

Key Features:

  • Responses are delivered asynchronously to your provided callback URL
  • Supports secure delivery via OAuth2 authentication
  • Enables optional consolidated response with Real-Time Eligibility (see below)

Requirements:

  • A callback API with an OAuth2 token endpoint using the Client Credentials grant type
  • Whitelisting of both the token endpoint and callback URL (standard SLA: 2 weeks)
  • Secure storage of client_id and client_secret credentials

For full implementation details, refer to the Customer Callback Example API Guide.


Option 2: Polling (Alternative)

If building a callback API is not preferred, customers may opt to poll for task completion using the Get All Coverage Discovery endpoint.

How It Works:

  • The Real-Time Eligibility response includes a Link header with one or more Coverage Discovery task IDs. See more documentation here
  • Customers must poll the Get By Id Coverage Discovery Endpoint for each ID until the task status in the root object is updated to either "success" or "failure" (i.e., no longer "pending").

Considerations:

  • Coverage Discovery tasks follow asynchronous paths and may take up to 72 hours to finalize (e.g., if enrolled in the COB or CI value-add path)
  • Polling frequency and volume should be managed carefully to avoid excessive traffic
    • For this reason, callback delivery is strongly recommended for high-volume use cases

Optional: Consolidated Response Model

Customers enrolled in Coverage Discovery may opt to receive a consolidated response that includes an abbreviated Real-Time Eligibility transaction embedded within the Coverage Discovery record.

Benefits:

  • Unified response simplifies integration and downstream processing
  • Reduces the need to manage multiple response streams

For response format details, download the OpenAPI Spec and refer to the /coverage-discovery/{id} response examples .

OAuth - Authentication with Client Credentials

A “token” endpoint must be provided that conforms to the OAuth2 specification. This endpoint should return an “Access Token” that Enhanced Eligibility can use to sign our Callback requests (ref). In addition, the “token” endpoint must use the “Client Credentials” grant_type (ref). Finally, the auth token URL must be within your pre-existing whitelisted domain from the step above. If not, then a new Firewall Rule must be configured that will come with a 2-week SLA.

Once whitelisted, customers must provide Optum Support with the following credentials to authenticate successfully with the Callback API:

  • client_id
  • client_secret

Whitelisting Requirements

Optum Domain Whitelisting

To enable secure communication between Optum and your systems, both the OAuth2 token endpoint and your callback API endpoint must be whitelisted by Optum. This allows Coverage Discovery to successfully send responses to the callbackUrl you provide.

  • A Firewall Rule must be configured for your domains.
  • This process typically follows a 2-week SLA.
  • We recommend using wildcard domain whitelisting to simplify configuration.

Example wildcard domain:
*.api.providercompany.com

What We Need from You

Please provide the following information to initiate the whitelisting process:

  • Domains
    Example: https://domain.com/callback & https://domain.com/token

  • CIDRs
    Example: 10.0.0.0/24

IP Whitelisting for Callback API Integration

To ensure successful integration with your callback API, please whitelist the following IP addresses. These IPs are used across Production and Sandbox

IP Addresses to Whitelist

  • 34.206.50.212
  • 54.85.40.151
  • 52.205.83.161
  • 35.173.102.15

↪️

Looking for the homepage? Return to Enhanced Eligibility Overview here.