Onboarding

Developer Onboarding Scope

This page is the developer-facing onboarding guide.

Use it for:

• technical prerequisites before implementation
• tenant and subtenant behavior
• callback versus polling decisions
• developer-side production readiness

Do not use this page as the source of truth for product enrollment, IMN onboarding ownership, provider versus channel-partner setup, or Medicare registration decisions. For those topics, see Onboarding for Providers & Channel Partners.

What You Need From Your Side

Use this checklist to determine what your team must provide before implementation begins.

Ownership and Responsibilities

Use the table below to align your product, support, and engineering teams with Optum before build work starts.

Recommended Onboarding Sequence

For the fastest path to production readiness, use this order:

1. Confirm which endpoints and workflows you intend to use: JSON or X12, real-time only or real-time plus Coverage Discovery
2. Confirm payer enrollment requirements and any value-added feature enrollment
3. Decide whether you need callback delivery, polling, or both
4. If using callbacks, design the callback API and OAuth token endpoint before requesting whitelisting
5. Complete domain whitelisting and customer-side IP allowlisting
6. Test in Sandbox with non-PHI data only
7. Validate your production correlation, persistence, monitoring, and support procedures before go-live

For most customers, the expected workflow is:

1. Submit Real-Time Eligibility
2. Let integrated Coverage Discovery trigger when configured conditions are met
3. Receive completion by callback or polling

Direct Coverage Discovery submission is supported, but it is typically appropriate only when your implementation already has a processed eligibility request/response pair and understands the additional input requirements.

Response Time And Enrollment Tradeoffs

Teams making enrollment decisions should understand the latency profile before choosing Coverage Discovery paths.

Real-Time Eligibility

Real-Time Eligibility remains synchronous, but end-to-end latency is driven mainly by payer and clearinghouse response time rather than Enhanced Eligibility platform processing time.

Key points:

• the downstream clearinghouse timeout is 2 minutes
• this accommodates slower payer connections and heavier traffic days such as the first or last day of the month
• current end-to-end RTE p95 is 20.7 seconds
• current end-to-end RTE p99 is 30.6 seconds
• current Enhanced Eligibility touch time p95 is 91.3 ms
• current Enhanced Eligibility touch time p99 is 171 ms

Coverage Discovery

Coverage Discovery is asynchronous. Discovery paths and add-ons are enabled per customer and are not included automatically.

Enrollment guidance:

• customers with strict response-time sensitivity should be cautious about enrolling in Coverage Insight
• the non-Coverage-Insight paths are generally near-real-time
• RTCOB is typically the longest of the near-real-time paths
• RTCOB should usually resolve within minutes and may take up to 30 minutes

Feature Enrollment

Work with the Enhanced Eligibility Support team to enroll in the value-added features that best align with your business needs. These features enhance standard eligibility processing with additional pre- and post-clearinghouse logic.

If deduplication is enabled for your tenant or subtenant, confirm these product decisions before implementation:

• the deduplication lookback window in days
• whether prior-month requests are excluded from the duplicate search
• whether deduplication applies to Real-Time Eligibility
• which Coverage Discovery paths use deduplication and which do not

This matters because deduplication affects when prior results may be reused. Some add-on features also include platform-managed reuse behavior that is separate from customer-configured deduplication.

For more details on available features, see the Value-Added Features page.

For product-side enrollment decisions, payer onboarding, and provider or channel-partner configuration ownership, see Onboarding for Providers & Channel Partners.

Authentication with Client Credentials

Enhanced Eligibility uses OAuth 2.0 Client Credentials for authentication.

During onboarding, you will be asked to provide an email address to associate with your credentials. We support:

• User-based credentials – each developer or API consumer receives their own credentials
• System-based credentials – a single set of credentials shared by an application or service

Once created, credentials are delivered securely to the provided email address.

See Getting Started for authenticating with the Enhanced Eligibility API and next steps.

Existing Medical Network Customers

If you are an existing customer of the Medical Network Eligibility API, 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.

This is a product and onboarding decision rather than an API implementation detail. For the business onboarding view, see Onboarding for Providers & Channel Partners.

Eligibility Payer List

For the current payer list supported by Medical Network, please download the list supplied in the "IMN Real-Time Eligibility" section in the Payer List UI. Use this document to find the "IMN Payer ID" to submit as the tradingPartnerServiceId on the Eligibility Request. If the specific payer requires enrollment, 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".

For broader payer enrollment and clearinghouse dependency planning, see Onboarding for Providers & Channel Partners.

Production Readiness Checklist

Before moving beyond initial sandbox validation, confirm the following:

• Your team knows whether you are using JSON endpoints, X12 endpoints, or both
• Your application generates and stores x-optum-correlation-id
• Your team knows which payer IDs to send and whether any payer enrollment is required
• Your team knows whether Coverage Discovery is enabled for your tenant
• Your team knows whether deduplication is enabled, what the lookback window is, and which discovery paths use it
• Your callback design is complete if you will receive asynchronous discovery results by callback
• Required domains are whitelisted and Optum egress IPs are allowed through your firewall if you are using callbacks
• Your team knows whether any x-optum-subtenant-id values were assigned and in which cases they must be sent
• Your support team knows how to capture x-optum-trace-id, timestamps, environment, and request examples for production issues

Data Tenancy (How your data is isolated)

Enhanced Eligibility is a multi-tenant platform, designed to securely support many customers while ensuring strict data isolation.

Your TenantId (automatic)

When you access Enhanced Eligibility through the Optum Marketplace:

• Your tenant ID is automatically assigned
• It is embedded in your API credentials
• You do not need to create, manage, or supply it yourself

Each request is automatically associated with your organization using the HTTP header:

x-optum-tenant-id

This header:

Identifies you as the customer
Controls access, configuration, and reporting
Ensures you can only access your own data

The x-optum-tenant-id is also echoed back in every response header. This allows you to confirm which tenant the request was processed under for debugging, auditing, or support purposes.
✅ You never need to set this header
✅ If provided manually, it is ignored to prevent misuse
✅ All behavior defaults to your organization’s configuration

From a product standpoint, this means tenant-level configuration is the default behavior for your organization unless Optum has explicitly assigned subtenant-specific behavior.

Serving Your Own Customers: Customer-Specific Configuration (Sub-Tenants)

Enhanced Eligibility supports customer-specific configuration through an optional concept commonly referred to as a sub-tenant.

Sub-tenants are used when a customer requires behavior that differs from the default tenant-level configuration, such as differences by downstream client, facility, or Coverage Discovery workflow.

What is a sub-tenant?

• Your tenant represents your organization and is automatically managed through your Marketplace credentials.
• A sub-tenant represents a specific downstream customer, facility, or workflow within your organization.

Sub-tenants allow Enhanced Eligibility to apply customer-specific configuration while continuing to operate under a single tenant and set of credentials.

Think of it as:

Tenant ID → identifies you
Sub-tenant ID → identifies your customer

When sub-tenants are used

Sub-tenants are commonly used when:

• A platform or channel partner runs eligibility on behalf of multiple customers
• A customer has multiple facilities or downstream clients
• Different Coverage Discovery behavior is required for different customers or facilities
• Configuration must vary by workflow while maintaining shared authentication

If this applies to your implementation, the Enhanced Eligibility Support team will explicitly inform you.

Using the sub-tenant header

Sub-tenants are identified using the optional request header:

x-optum-subtenant-id

Important rules:

Only send this header if explicitly instructed by the Enhanced Eligibility Support team
The value is assigned and provided by the Enhanced Eligibility team
Values must not be generated, inferred, or derived by clients
A customer may be assigned one or more sub-tenant IDs as needed

Subtenants are typically used when the same authenticated client needs different payer, facility, or Coverage Discovery behavior for different downstream customer contexts.

For example, if a customer has multiple facilities or downstream clients with differing Coverage Discovery requirements, the Enhanced Eligibility team may assign a distinct sub-tenant ID for each, with each value controlling the appropriate configuration.

Error handling and validation

If a sub-tenant ID is sent that has not been assigned or configured, the request may fail with:

• Processing errors
• Permission or authorization errors
• Rejection prior to business logic execution

⚠️ Do not populate x-optum-subtenant-id unless you have been explicitly instructed to do so.
If you have not been assigned a sub-tenant ID, simply omit this header. Enhanced Eligibility will continue to process requests using your tenant-level configuration.

Coverage Discovery: Callback and Polling Options

This section explains the technical delivery models developers must implement after Coverage Discovery has been enabled. For the product decision to enroll in Coverage Discovery, see Onboarding for Providers & Channel Partners. For the endpoint contract and payload examples, see Customer Callback Example API.

Choosing The Discovery Entry Pattern

Most customers should enter Coverage Discovery through integrated Real-Time Eligibility.

Use direct Coverage Discovery only when your implementation already has the required processed eligibility data available and you intentionally want to submit discovery work separately from the original real-time request.

For integrated real-time workflows, the original real-time eligibility exchange provides the source data used by the downstream Coverage Discovery workflow.

If you do need direct discovery:

• POST /coverage-discovery/x12 is often the easier path because it accepts the processed x12-270 and x12-271
• POST /coverage-discovery is more specialized because it always requires canonicalEligibilityRequest and may also require canonicalEligibilityResponse depending on the enrolled workflow

Direct JSON discovery rules:

• canonicalEligibilityRequest is always required
• whether canonicalEligibilityResponse is also required depends on the enrolled workflow
• confirm the expected direct-discovery payload with Optum if your implementation uses canonical JSON

Naming model:

• the root Coverage Discovery record name is the configured task name assigned by Support for the workflow you are enrolled in
• each discoveryPaths.*[].name value identifies the specific path that ran for that record
• common path names are Medicare, Commercial, RTCOB, CoverageInsight, Medicaid, HMO, and dynamic Search Option names such as Search - <generated value>

Delivery Options

Coverage Discovery is a long-running asynchronous process. Customers enrolled in this capability may use callback delivery, polling, or both to receive completed task responses. For most production implementations, callback delivery is the primary model and polling is the fallback model.

For proof-of-concept work or temporary stop-gap use cases, Optum may also be able to produce a batch file containing x12-271 responses generated from Real-Time Eligibility and/or Coverage Discovery processing. This can reduce the need to build immediate high-volume pagination over the Transactions or Coverage Discovery list endpoints while callback or polling workflows are still under development.

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
• Idempotent processing of repeated deliveries for the same discovery task id
• Operational ownership for callback downtime, token expiry, and recovery testing

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. Polling may also be used alongside callbacks as a fallback validation path.

How It Works:

• The Real-Time Eligibility response includes a Link header with one or more Coverage Discovery task IDs. See more documentation here
• Direct POST /coverage-discovery requests return a location header for a created task when a single task is accepted
• Customers should 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:

• completion times vary by enrolled workflow and feature mix
• 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
• Your application should persist the discovery task id from the link or location header instead of relying on list searches alone

Option 3: Temporary Batch File For POCs

For customers who need a temporary proof-of-concept delivery path before polling or callback delivery is fully implemented, Optum can sometimes produce a batch file containing x12-271 responses created from Real-Time Eligibility and/or Coverage Discovery processing.

This option is particularly useful when:

• your team is still building the polling solution
• your callback or postback endpoint is not ready yet
• querying GET /transactions or GET /coverage-discovery at scale would require burdensome pagination

When available for your implementation, the batch file can be delivered securely through ECG Quick Connect or directly to the customer through an agreed secure channel.

This should be treated as a temporary stop-gap measure rather than the target-state asynchronous integration model.

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

Operational notes:

• realTime provides related real-time eligibility context when that option is enabled
• discoveryPaths.*[].transaction contains transaction details for individual discovery results
• customers typically retain the identifiers, statuses, and response elements needed for their operational workflow

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

Your token endpoint and callback endpoint are customer-owned interfaces. Optum must be able to reach them from the IPs listed below.

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

• Environment mapping
  Which domains are used for Sandbox versus Production

• Technical owner
  Who can validate connectivity, authentication, and retry behavior during implementation

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. This allowlist applies to outbound Optum connections into your customer-owned token and callback endpoints.

IP Addresses to Whitelist

• 34.206.50.212
• 54.85.40.151
• 52.205.83.161
• 35.173.102.15

Related Guides

• For product onboarding and configuration ownership, see Onboarding for Providers & Channel Partners
• For first requests, key headers, and developer tooling, see Getting Started
• For feature descriptions and enrollment context, see Value-Added Features
• For callback implementation details, see Customer Callback Example API
• For support workflows, see Troubleshooting and Support

↪️

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