Eligibility FAQs

What does a typical Eligibility API response look like?

You may receive lengthy responses to our Medical Network APIs, due to the many data points that a payer or trading partner provides in the query response. It reflects the needs to inform the provider about the various financial components of the patient's insurance coverage — existence of copays and co-insurance payments; deductible amounts; possible dependents information; coverage levels, and much more.

Please see response example Eligibility request & response.

👍

TIPS

• You will see the serviceTypeCodes value on all responses, and is repeated several times in the benefitsInformation object depending on the length of the response and the business lines of the payer. Visit Service Type Codes for a complete list of the service type codes.
• If the payer supports only a single category of inquiry in the Eligibility requests, you will see serviceCode 30 for Health Benefit Plan Coverage. Some payers typically give a serviceCode 30 to affirm that the patient has active health insurance coverage.
• Some payers will reply with shorter responses than others; the Eligibility API Response body example is a briefer one that you can see by testing the tradingPartnerServiceId value of AETNA in the request.
• The insuranceTypeCode denotes the type of insurance policy within a specific insurance program. Payers can support numerous types.
• For a more in-depth breakdown of each JSON object, see Eligibility response.

I am using the nuxt3 framework inside the server API. For some reason, I am having an issue getting a response back on both my own server and when using the testing functionality on the change testing site with the inline try its features.

A value in the tradingPartnerServiceId field might be missing. Use the value in the request body from this sandbox values list. Scroll down to view different responses based on that tradingPartnerServiceId field.

What are the following attributes for Encounter entity used in Eligibility 270 request?

Please see description in Glossary.

Does "Active coverage" mean that the services are covered by 100%, or does it only indicate that the services are covered but the details of the coverage will be provided below?

Please see Glossary.

What does the benefit type "Other or Additional Payer" mean, and why does it have no benefit information?

Please see Glossary.

In certain responses from certain Payers, it can be seen that a deductible is mentioned for Health Benefit Plan Coverage (serviceType code 30) whereas, no deductible is mentioned for other benefits returned in the same response by the payer. In such cases, is the deductible amount mentioned in Health Benefit Plan Coverage applicable to the rest of the services as well?

Typically, the deductible would only apply to the specific service type code that is being returned and referenced in the same object. If the information is not being returned for the other service type codes, that would most likely mean that there is no deductible for the specified service.

What does eligibility information look like when you receive it from the Payer?

The Eligibility response provides the complete status of the requested patient's medical insurance. It can provide details of medical coverage for dozens of medical specialties, or it can simply confirm that the patient has current medical insurance (or otherwise). In this topic, we will describe the types of information you can expect to find in this body of information:

• where you can expect to find it
• what the medical benefits look like
• how the Eligibility response describes medical benefits for medical services

How and from where I can get the controlNumber for Claim and Eligibility API?

Please see definition in Glossary.

Using search options to optimize queries

Please see Search Options to Optimize Queries.

X12 EDI Support

We support a dedicated X12-formatted Eligibility API to send your submission in X12 EDI format. It supports the standard syntax for a complete X12 EDI 270 transaction set.

The Eligibility API enables you to quickly look up a patient’s insurance benefits. Check co-insurance, co-pays, deductibles, and expected out-of-pocket amounts with other insurance benefits, for a subscriber or dependents of the subscriber for a policy.

The Eligibility endpoint also allows you to request eligibility for service types. The optional serviceTypeCode parameter allows you to specify particular service(s) in a request. If you do not specify a service type, the API makes the request for general benefit coverage information (this is also enabled by specifying the default serviceTypeCode 30).

Eligibility and benefit responses vary depending on the trading partner and the health plan in which a member is enrolled. Our API returns all information received from the trading partner in the Eligibility response.

How do Raw-X12 Eligibility requests and responses work?

We support an X12 EDI Eligibility request if you choose to implement the 270 transaction set in its native EDI format. The responses you receive will also appear in EDI format.

📘

NOTE

Before using the Eligibility /raw-X12 endpoint, contact your Optum implementation analyst. Our Raw-X12 service requires custom headers with credentials, and other information specific to each customer's contracted Payer List relationships that you will need to obtain from your analyst contact.

We also support an X12 EDI Eligibility request if you choose to implement the 270 transaction set in its native EDI format. The responses you receive will also appear in EDI format. Please see example in X12 EDI 270 Request & 271 Response.

Ensuring Integrity of X12 transmissions

When you create and send your X12 content through our API, ensure that the final field in the ISA header, ISA16, contains the colon character (":"). ISA16 is a single-character field that defines the component element separator in the ISA header. For your X12 EDI transactions to work in your contracted APIs, you must use the colon character (":") in this field. It should be used only in ISA16 and not for any other X12 header or trailer. See Appendix C of the ASC X12 270 Implementation Guide for more information about the Eligibility transaction structure.

📘

NOTE

Before using the Eligibility /raw-X12 endpoint, contact your Optum implementation analyst. Our Raw-X12 service requires custom headers with credentials, and other information specific to each customer's contracted Payer List relationships that you will need to obtain from your analyst contact.

Eligibility Raw-X12 endpoint

https://sandbox-apigw.optum.com/medicalnetwork/eligibility/v3/raw-x12

📘

NOTE

Check the Eligibility API Mappings document in the Attachments tab for a complete Eligibility EDI loop and segment mappings to the JSON fields in the Eligibility 270 requests and 271 responses.

X12 EDI Eligibility request

Please see example in X12 EDI 270 Request & 271 Response.

When do I need to use a Dependent object in my submissions?

A Dependent can be considered the patient for an Eligibility query. Two straightforward criteria together, determine how a dependent is managed for an Eligibility request and any follow-up medical claims:

• The patient is defined as a dependent on an insurance policy member's subscription;
• The dependent patient cannot be uniquely identified in the payer's medical membership database or any information other than in the subscriber's policy.

If the patient is the stated dependent on a member's policy but can also be uniquely identified by the payer through having an existing Member ID number or other insurance identification, the dependent must be identified in the Subscriber object for any related medical claims. They will be considered the Subscriber for the medical claim purposes.

See Eligibility JSON to EDI mappings and Eligibility OpenAPI Spec for more information.

What about cases where a subscriber/patient does not have/is not covered by a medical plan/associated plan?

Please see example in Without Active Coverage (Subscriber) from a Medical Plan.

Is there a way that the Human Readable View can be exposed through API so we can surface that information directly in our UI?

The specific information can be located in the insuranceTypeCode and insuranceType fields in the JSON. The insuranceTypeCode is used as a code that Identifies the type of insurance policy within a specific insurance program. Following is a list of the possible values. At this time, this is the only information that can be returned through the API JSON or X12 version of the transaction. To obtain a license that also provides access to the full requirements for these transactions, visit x12 org.

Why do I see an NPI error when I run the Eligibility API endpoint?

Please see NPI error.

Is it possible to proceed without this Provider ID if we submit the request with just the Provider Name and NPI?

Yes, you can submit an Eligibility request with just the provider name and NPI. The Bare Minimum Eligibility Request example does not include it. Most payers respond with minimum amount of information.

What is reassociationKey? And how can we associate with response if we get some error from API?

Please see example in Glossary.

Is there a way to reduce the number of requests by grouping the service types together? Which payers allow that and which don't?

We do not know which payers allow more than one serviceTypeCode. However, we recommend no more than two in a single request.

In the Provider object, if we are submitting on behalf of a specific provider within a practice, can we still use firstName and lastName? Or do we have to use OrganizationName?

You can use firstName and lastName.

Is the gender field required for the subscriber object? What if the subscriber’s gender does not fall into M or F?

It is not a required field, however, depending on the request — for example, maternity benefits — would only apply to a female. If the patient is not specifying a gender, leave it blank.

What exactly is required for a Bare Minimum request?

The companion guide (X12) will identify the fields that are required and which are situational. The Bare Minimum request samples give you an idea of what you can send as the bare minimum amount of data in order to get a response if the patient has coverage with that payer.

Can I get the .csv to the Eligibility Payer Guide comprising the Payer Name, Payer ID, and X12 requirements?

Here is a link to the X12 site where you can get the X12 Technical Report (also known as TR3) that give you the specification and information around each healthcare transaction. You have to license this from X12.
However there is a CMS companion guide that you can download.

The individualRelationshipCode field did not exist before, is it an optional field in production? Should this field be added to the call and what are its pros and cons?

This is related to dependent's information, the following is from the TR3:
Individual Relationship Code M 1 ID 2/2
Code indicating the relationship between two individuals or entities
OD — 271B1_2100D_INS02__IndividualRelationshipCode
CODE DEFINITION
01 — Spouse
19 — Child
20 — Employee
21 — Unknown
301144 — Use this code if the relationship code of Unknown is valid for this person when received in the 837 2000C.
PAT01
OR — Use this code if relationship information is not available and if there is a need to use data elements
INS03, INS04, or INS17.
39 — Organ Donor
40 — Cadaver Donor
53 — Life Partner
G8 — Other Relationship

How do we know about the Coverage Type using API? How do we know about the Plan Start and End Dates using API?

You can find out information if the patient has active coverage or not, and the start and end dates along with all of the financials (co-pay, co-insurance, deductibles, and so on) in contents of Eligibility response.

I am using the nuxt3 framework inside the server API. For some reason, I am having an issue getting a response back on both my own server and when using the testing functionality on the change testing site with the inline try its features.

You do not have a value in the tradingPartnerServiceId field. Use the request body from this list sandbox values list. Scroll down to view different responses based on that tradingPartnerServiceId field.

Should Eligibility ID be used for checking eligibility, Claim Status ID for checking claim status, and Payer ID for submitting claims?

Yes, if Eligibility ID is not available, use the Payer ID.

How to pass Patient API and how to send you our patient information?

Part of the Eligibility request is to include the patient information, first name, last name, member ID, and so on. Here is what a typical eligibility request includes. Yes, you must send the patient information separately through an API.

When I execute the eligibility/v3 API, I can see many benefitsInformation objects with different serviceTypes and benefitAmounts, sometime, same serviceType has different benefitAmount. Is there a way to decide which one to use?

We provide different examples of what could come back in a response. There is not really a right or wrong answer, this is to let you know that this information could come back in a response.
Review the JSON-to-EDI mapping documentation, which might help you understand what the different EDI responses are, and why they come in the way they do. Obtaining a copy of the X12 Implementation Guide may also be helpful.

Submitter ID is required to make an eligibility check, is there any documentation related to how Submitter​ IDs are created? If we have child accounts underneath our parent account, will each of those child accounts have its own Submitter ID? Do we need to provide Submitter ID when making eligibility calls to Change? If so, what field does that map to?

Please see Submitter ID in Glossary.

Are any actions required to perform eligibility checks with carriers that do not require enrollment?

When you are supplied your production credentials, you can start sending Eligibility checks to payers that do not require enrollment. Making sure, of course, that you can send a syntactically correct Eligibility request to get a response. You can also immediately perform an Eligibility check within the ConnectCenter if needed too.

For a Bare Minimum Eligibility request, what values do we send for these request object keys?

• tradingPartnerServiceId is the Payer ID you will need to request benefit information from an insurance carrier. Here is a list of test tradingPartnerServiceId.
• serviceTypeCode '30' is the most common and provides general benefit information in the response. Depending on whether or not the specific eligibility information is required, the serviceTypeCode may change. Here is a complete serviceType code list.

Eligibility v3 API throws the 79 (Invalid Participant Identification) error when the CMSMED is passed as the tradingPartnerServiceId. It is not even working on the dashboard and throws the same error. Are the any extra details do we need to send while checking eligibility for the medicare insurance?

Please see 79 Invalid Participant Identification section in error messages section.

Some responses have policyNumber and planInformation while some do not have. How can I get that? Is the policyNumber same as the subscriber's memberId?

For a background, the identifiers within the planInformation object are additional identifiers that a payer might send back when it is helpful to have more information than just the memberId. The main identifier for the member is typically the memberId, and that value will come back in the subscriber object. This is a required field, so you should be getting this back consistently.

The additional IDs in the planInformation are optional fields for the payer to return, and so you may see different fields come back based on who you are sending the request to. For example, Aetna may return more or less information than Cigna would. See more information on these fields.

If there is ever something critical that a payer should be returning that is not in the response, our Eligibility support team may be able to help troubleshoot.

How can I get member copay, deductible apart from status in the eligibility response API?

The member's co-pay and deductible will appear in the response when it is applicable. Some health plans may not have a deductible or have co-insurance rather than a co-pay, so those fields will not always be present.

In sandbox, we have a range of emulated payer responses that you can test with. These are found by changing the value of the tradingPartnerServiceId field in the request with the values located on this page sandbox predefined values and test responses.

When I enter wrong memberId or birthdate, the Eligibility API takes a long time to respond on a live server, can you help?

The Eligibility API communicates with the payer's database in real-time, and we have found that some payers have high response times during peak volumes. If you are in production and want to troubleshoot, please work with your implementation analyst.

If the Eligibility API is not guaranteed to provide plan or benefit information, how do we determine the co-pay if we do not have the card?

The item to clarify is the data contained in the Eligibility response. If you get a successful response from the Eligibility API based on the patient information in the request, that data is coming directly from the source of truth, which is the payer. The variance you might find is differences in the kinds of data returned between payer-to-payer or between plans. If a patient has a co-payment that the payer wants you to know about, it will be contained in the response. Benefits listed as co-payments are generally collected from the patient at the point of service, and this is typically understood by the payer. The details can vary between payers or plans, so if in doubt, you should always clarify with the payer.

Complete the information on the patient responsibility and other usage information for the Eligibility transaction can be found in the X12 270/271 Implementation Guide. That industry guide is licensed and is available for purchase from the X12 organization.
Here is an example snippet from the Eligibility API in sandbox: how to determine co-pay without a card using tradingPartnerServiceId as UHC.

Eligibility API is giving "unable to process the request at this time, please try again later"? In Postman, the auth API gives Either client_id or client_secret are invalid, when using correct value for both. It works via curl though.

Please see the Eligibility API: Unable to Process the Request at this Time section for more information.

How can I interpret the service level information from the sandbox response?

Please see example in Interpret Service Level Information from Sandbox Response.

To know patient copay/coinsurance for the visit (probably service type 98) and also for the mental health as covered by the plan, should I be running multiple requests for 98, MH, and A6 for each patient to get complete eligibility? Is there a better combo of service type codes that can yield me the results with lesser number of requests per patient?

98, MH, and A6 are good, include 30.

Is there a code I can use specifically for telehealth coverage? I do not think you cover any codes after 2009 or the 3 character code of E37 I found on the X12 website.

Unfortunately when the guides came out, Virtual and Telemedicine were rarely used, and hence there are no specific code designations or standards on how it should be returned. You could use a different service type code (we have seen 98, 30, 9, and there probably are other variances).
Normally though in a MSG, they will have something like: MSG\*VIRTUAL VISITS/TELEMEDICINE/TELEHEALTH~.

Is there a list of all the rejection codes for validation when submitting claims?

We have a basic list of AAAError codes. Additionally, a list of Claim Status response codes that are maintained by the X12 organization. Lastly, we have a list of Optum edits available in the ConnectCenter >> Payer Tools tab >> Edit Search option for more error messages and their description. Based on the edit message being returned the information may be entered in the incorrect location as the information should be specific to the patient.

How can serviceTypeCodes be used to identify business groupings?

Please see example in Use ServiceType Codes.

When there are no timeQualifiers attached to Co-insurance or Co-payment, does this mean that the patient is required to pay based on the values specified for Co-insurance or Co-payment in any scenario?

Please see definitions in Co-insurance and Co-payment.

Sometimes both Co-insurance and Co-payment are specified together for the same service, time qualifier, coverage level, and plan indicator. What does this signify? Should the user pay both, or does one supersede the other?

The co-payment should be collected at the time of service, a co-payment is a fixed rate you pay for prescriptions, doctor visits, and other types of care. Co-insurance is the percentage of costs you pay after you have met your deductible.

Are there specific relationships between time qualifiers and benefit names? For example, is there a predefined list of time qualifications that should be associated with co-insurance, co-benefits, out-of-pockets, deductibles, etc., or not?

Please see a list of Allowed Time Qualifier Reference.

Do you support checking if a members insurance covers specific service events (based on CPT Code)?

We do not support CPT codes in the Eligibility request, however, sending over a '30' in the serviceTypeCode, typically brings back all the benefit information for a patient.
There is also a list of serviceType codes you can refer to, in X12.org. MH is another serviceTypeCode that could be used for mental health benefits.

Will a Payer send same ERA to multiple clearinghouses?

Most payers typically only allow ERAs to route to a single clearinghouse. Clearinghouse can route ERAs to multiple submitters internally, but a payer would only ever route to a single clearinghouse. Availity is a clearinghouse used as a trading partner. We use Availity and many other trading partners to facilitate connections to payers. They are the sole receivers of the data from the payer but Availity then forwards the information to us.

Can I use the Eligibility API to conduct eligibility checks on patients that are a part of The Health Reform Act for Preventative Care?

Currently, the API only allows for the submission of serviceTypeCode. Submission of specific CPT and Diagnosis codes is not currently supported within the current spec. Information, such as Medical benefits, Copays/Deductibles/Other notes, and number of visits are returned. A sample response can be found here.

Some Payer Names share the same 'Payer ID' and 'Payer Type,' but differ in terms of 'Service Name' and 'Alternative Payer Name.' When selecting a 'Payer Name' as the Primary Insurance for a patient, will the Eligibility Request and Claims be sent using the corresponding Payer ID and Payer Name?

It will be sent to the payer based on what the submitter sends as the payer ID and payer name.

Does the 'Alternative Payer Name' serve only to differentiate the Payer and not have any significance when sending Eligibility and Claims requests?

The Alternative Payer Name is typically another name the payer may have had or another name they may be known as.

Need clarity about the information required for the 'tradingPartnerServiceId' parameter, should we pass the Payer ID or the 'Eligibility ID' for this parameter?

The request should have a valid tradingPartnerServiceId in it. This is the value you find in the payer list on the ConnectCenter in the 'Real-Time Payer ID' column. If none is listed in that column, check the 'Connectivity Available' column, which is for CS/E. If there is a 'P' in the second entry, there is a Portal connection available for Eligibility. If the fields in that column are N/A, there is no connection for CS or Eligibility to that payer. If there is no connection with that payer, you can fill out a New Payer Connect Request form found at the top of the payer search result screen and an internal team at Optum would look into the feasibility of a connection being made to that payer.

If you are not contracted with Optum, please use the sandbox predefined values to test our APIs.

Should the CHC Payer ID be included in the TradingPartner Payer ID?

The tradingPartnerServiceId would be either the CPID for claim submissions or the Real-Time Payer ID for Eligibility transactions. The list of payers can be found by signing into ConnectCenter.

1. Go to Payer Tools >> Payer Search.
2. Select the associated products and click search.
3. Download the list using the .CSV link in the top right corner.

Error, 'Please use predefined canned users for non-prod environments: lastName was not predefined' while submitting Eligibility API request

The sandbox is PHI free, and only allows the predefined canned users to be sent in sandbox transactions. To send requests with anything else, the production environment should be used.

Is there a maximum duration limit for the start date and end date of the Date of Service in the Eligibility API?

Typically, most commercial payers only return information for the current calendar year. The expectation to this are, Medicare and Medicaid; the start date would typically be when the individual reaches age of 65 or some under 65, with certain disabilities or conditions. There is technically not a maximum duration limit for the start and end date for Date of Service. The values are valid as long as they are expressed in a CCYYMMDD format.

How can I add new payer to the Eligibility trading partner payer list?

Please see example in Add a New Payer to Eligibility Trading Partner Payer List.

Does Eligibility API return if it is a Medicare patient, including managed Medicare?

Yes, if you are submitting the request to Medicare, they would return additional information related to specific insuranceType, which allows you to determine if the benefits apply to Part A, Part B, or another insurance. Please see example in Eligibility Response for Medicare Patient.

Does the Eligibility API return if the rendering provider is in network or out of network with the insurance plan?

No, the in- and out-of-network indicators on the transaction only indicate how the benefits should be applied in those specific situations for those service type codes. They do not indicate if the provider is in- or out-of-network. This would need to be confirmed directly with the payer.

Eligibility in production: what values to be filled in ISA06 and ISA08?

Please see example in Required Fields in ISA06 and ISA08.

Is it possible to identify which payer maps which CPT and ICD-10 under which STC through the eligibility API, or do we need to figure this out one-by-one for each concrete payer?

We would not have this information available at our end. We recommend you to review the individual payer companion guides that are published by each payer. These are typically publicly accessible resources that are available on the payer’s website.

What do "Active Coverage" and "Non-Covered" mean (in the "benefitsInformation")? There are no deductibles nor co-insurance mentioned in those objects.

Please see definition in Glossary.

Where can I find the annual deductible and Out-Of-Pocket (Stop Loss) in the response? I couldn't find this information in the example request-response for John Doe in the sandbox.

There are different test scenarios available in the developer portal, which lists specific situations. These different scenarios can be accessed by changing the tradingPartnerServiceId in the sandbox request. A list of available responses can be found in Sandbox API Values and Test Responses.

How can I determine the list of all providers where the services are covered?

This would have to be confirmed with the payer. The eligibility response does not confirm if the provider on the request is in or out-of-network.

Are the terms of benefits different among providers within the same healthcare plan for the same subscriber?

Yes, the benefits would differ based on the specific provider. The providers need to confirm if they are in or out-of-network.

How can we determine if pre-authorization is required for certain services, and if so, where can I find this information in the response?

This would need to be confirmed with the payer directly. We do have prior authorization products available but they would be a separate product offering.

I am submitting a request with GET method, after requesting, I get the Transaction ID with a response, do I need any link or URL for getting the data with the Parameter Transaction ID? How can I trace my transaction with the help of Transaction ID?

There is not a way to search by the submitted transaction ID on an eligibility request. Here is a screenshot of the ConnectCenter, which would be the primary way of searching for a submitted request. Please see example in Search an Eligibility Request by Transaction ID.

I have used other providers for benefit checks and they often return the rate table that the insurance will use to price out-of-network claims (e.g. MNRP, UCR, Medicare @ 110%). I don't see that information returned in the general eligibility response. Am I overlooking it or not using the right endpoint?

Please definitions in Glossary.

How many different codes can be found under "benefitsInformation", such as "Non-Covered", "Active Coverage", "Deductible", "Co-Insurance", etc.? Where can I find explanations for these codes?

This code is used to identify the eligibility or benefit information. This may be the eligibility status of the individual or the benefit related category. Please Benefits Information Codes in Glossary.

Provide a brief explanation of how dependent coverage works? How can we distinguish the benefits associated with the subscriber from those for dependents?

Please see Dependent Coverage definition in Glossary.

Is it necessary to use the "Family" indicator in benefits to signify that a particular benefit applies to dependents, or is there an alternative solution? If so, does this imply that all dependents under the same policy share the same coverage terms?

Please see Family Indicator definition in Glossary.

Do subscribers and dependents under one policy have identical coverage terms?

No, typically there are specific coverage terms for the subscribers and dependents.

Other than the benefit codes, what other factors influence the coverage for the subscriber or dependents that affect the calculation of the customer's responsibility?

Please see Benefits Information Codes in Glossary.

How to find Deductible and Copay in Eligibility API response?

The co-pay or deductible information is returned in the BenefitsInformation object. The first two values in each segment, code, and name, identify the top-level benefit information. If you see codes A, B, C, G, J, or Y, the current object is describing a patient responsibility (co-insurance, co-payment, deductible, and so on). This in conjunction with the benefitsDateInformation, will be used to determine the amount due at a specific time. The benefitsDateInformation describes the insurance coverage dates. Its data consists of two dates:

1. the Plan Begin Date (or the date from the preceding 18 months from the current submission date, whichever is more recent);
2. the eligibility submission date.

What is an idCard in eligibility API Subscriber object ?

The idCard is used when the Identity Card Number is different than the Member Identification Number. This is mainly prevalent in the Medicaid environment.

If a subscriber has a health insurance plan that covers family members, and the deductible for an individual under the plan is $500, while the deductible for the entire family is $1000. For example, if the subscriber pays $300 for a consultation, does both the remaining individual and family deductibles decrease, or only the individual deductible?

For most family plans, the whole family has a shared deductible, and each family member has an individual deductible that counts toward the family deductible. The family's deductible is met when any combination of family members' healthcare costs meet the maximum deductible for the whole family. This is specific to each policy and would need to be confirmed individually.

Does both the remaining individual and remaining family deductibles decrease, or only the individual deductible for In-Network and Out-of-Network providers: What if a user pays for an in-network provider? Does it decrease the deductible for out-of-network services as well or not?

If you have separate deductibles for in-network and out-of-network care, the amount you have already paid toward your in-network deductible does not count toward your out-of-network deductible. These would be separate amounts and would not count towards each other.

Related Topics

• API Reference
• Troubleshoot APIs with Metadata