Eligibility FAQs
NOTE
Please see the API FAQs section for tips and solutions to some of the most common questions asked by customers, developer community, and internal staff about the use of the Change Healthcare API.
What is the Eligibility API? Wondering what kind of services it provides and the benefits of the product?
The Eligibility API is an easy way to check if a patient has healthcare coverage with a specific insurance company (payer). For example, if I were to schedule an appointment with my doctor for some reason, the first thing they are going to ask for, is my insurance card, and then run an eligibility call to my insurance company to verify that I have insurance. The response of that eligibility call will also provide how much my co-pay is.
Visit our developer portal for specific documentation.
This service uses the standard X12 EDI 270 Eligibility transaction, and formats it in JSON for an HTTP request. It makes this popular EDI transaction set more accessible to developers and to users' applications. We manage the X12 standards behind the scenes and give you efficient access to medical subscriber or dependent plan membership, copays, coinsurances, deductibles, and more in an easy-to-use, human-readable format.
Our Eligibility API solution provides complete patient profile and benefits information to support healthcare delivery and more-efficient and accurate reimbursement. Providers get better front-end information to improve claiming processes and reimbursement rates. For payers, it means claims spend less time in pending status, and also means fewer rejected and reworked claims.
Is there a best practices checklist and workflow for Eligibility API?
Yes, refer to Eligibility API Best Practices & Workflow guide.
What does a typical Eligibility API request look like?
The Eligibility API uses a POST
request. You can provide the input as JSON in the body of the request. While the request may be relatively brief, the responses may contain substantial information.
Request body example
```json
POST ${api_basepath} HTTP/1.1
Host: ${apigee_host}
Authorization: Bearer <Your-Access-Token>
Content-Type: application/json
{
"controlNumber":"123456789",
"tradingPartnerServiceId": "serviceId",
"provider":
{
"organizationName": "provider_name",
"npi": "0123456789",
"serviceProviderNumber": "54321",
"providerCode": "AD",
"referenceIdentification": "54321g"
},
"subscriber": {
"memberId": "0000000000",
"firstName": "johnOne",
"lastName": "doeOne",
"gender": "M",
"dateOfBirth": "18800102",
"ssn": "000000000",
"idCard": "card123"
},
"dependents": [
{
"firstName":"janeOne",
"lastName":"doeOne",
"gender":"F",
"dateOfBirth":"18160421",
"groupNumber": "0000000000"
}
],
"encounter": {
"beginningDateOfService": "20100101",
"endDateOfService": "20100102",
"serviceTypeCodes": [
"98"
]
}
}
```
In most cases, Eligibility is a straightforward insurance membership query. As shown here, the core request information consists of several JSON objects of the provider and subscriber/dependents information, the date(s) of the medical encounter and the provider services rendered during the encounter. The amount of information depends on the information the provider needs to submit as the initiating request for the Eligibility transaction.
The preceding example lists a serviceTypeCode
of 98
, indicating that the Eligibility request is inquiring about the patient's insurance benefit covering a visit to a physician's office. Some payers will support a number of specific service type codes to drill down into benefits coverage; some will not, and will support only a verification of core medical insurance coverage. Those requests and responses will show a value of 30
in those cases.
NOTE
If you submit an Eligibility request with a serviceTypeCode other than 30 to a payer that does not support other more-specific code values for this information, you will receive a generic response equaling the standard one of 30, describing whether or not the patient has active coverage.
Is the usageIndicator field something that is respected by the clearinghouse and/or payers? Is submitting real data with a "T" usageIndicator value a valid way to test production data without actually submitting it for processing? How is this field interpreted?
You are correct. Sending a claim with the "T" usageIndicator is a valid way to test production data without submitting for processing. The claim will be passed through our clearinghouse edits, including any payer specific edits for the payer listed on the claim. Clearinghouse reports will be returned, but if the claim is accepted, it will not be sent to the payer for further processing.
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.
Response body example
```javascript
{
"controlNumber": "123456789",
"reassociationKey": "123456789",
"tradingPartnerServiceId": "AETNA",
"provider": {
"providerName": "provider_name",
"entityIdentifier": "Provider",
"entityType": "Non-Person Entity",
"npi": "0123456789"
},
"subscriber": {
"firstName": "johnOne",
"lastName": "doeOne",
"gender": "M",
"entityIdentifier": "Insured or Subscriber",
"entityType": "Person",
"dateOfBirth": "18800102",
"ssn": "111111111",
"provider": {}
},
"subscriberTraceNumbers": [
{
"traceTypeCode": "1",
"traceType": "Current Transaction Trace Numbers",
"referenceIdentification": "123456789",
"originatingCompanyIdentifier": "9EMDEON999"
}
],
"payer": {
"entityIdentifier": "Payer",
"entityType": "Non-Person Entity",
"name": "Unknown",
"payorIdentification": "AETNA"
},
"planInformation": {
"socialSecurityNumber": "111111111"
},
"planDateInformation": {
"plan": "20160818-20160818"
},
"planStatus": [
{
"statusCode": "1",
"status": "Active Coverage",
"planDetails": "QMB",
"serviceTypeCodes": [
"30"
]
}
],
"benefitsInformation": [
{
"code": "1",
"name": "Active Coverage",
"coverageLevelCode": "IND",
"coverageLevel": "Individual",
"serviceTypeCodes": [
"30"
],
"serviceTypes": [
"Health Benefit Plan Coverage"
],
"insuranceTypeCode": "QM",
"insuranceType": "Qualified Medicare Beneficiary",
"planCoverage": "QMB",
"benefitsDateInformation": {
"benefit": "20160818-20160818"
}
},
{
"code": "R",
"name": "Other or Additional Payor",
"coverageLevelCode": "IND",
"coverageLevel": "Individual",
"serviceTypeCodes": [
"30"
],
"serviceTypes": [
"Health Benefit Plan Coverage"
],
"insuranceTypeCode": "WA",
"planCoverage": "MEDICARE PART A",
"benefitsDateInformation": {
"plan": "20160818-20160818"
}
},
{
"code": "R",
"name": "Other or Additional Payor",
"coverageLevelCode": "IND",
"coverageLevel": "Individual",
"serviceTypeCodes": [
"30"
],
"serviceTypes": [
"Health Benefit Plan Coverage"
],
"insuranceTypeCode": "MB",
"insuranceType": "Medicare Part B",
"planCoverage": "MEDICARE PART B",
"benefitsDateInformation": {
"plan": "20160818-20160818"
}
}
]
}
```
In many cases you will see a much larger body of information in the Eligibility response, depending on the level of detail supported by the payer.
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 aserviceCode
30 to positively affirm that the patient has active health insurance coverage.- Some payers will reply with shorter responses than others; the preceding example is a briefer one that you can see by testing the
tradingPartnerServiceId
value ofAETNA
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.
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?
The controlNumber is a random or auto-generated number that you create and send to us for each transaction. That unique number helps with any troubleshooting and tracking of the transaction when you are 'Live' with us.
Here is the definition from our documentation from our developers portal:
ControlNumber — a single arbitrary value that the requestor defines in the initial Eligibility API transaction request, perhaps by a random number generator. All parties to the Eligibility transaction refer to this number to ensure accurate responses and completion of the exchange.
ControlNumbers must be defined as a nine-digit unsigned numeric value.
Using search options to optimize queries
A search option is a set of related fields that will yield a successful eligibility response from a payer if there is a member match.
Trading partners typically require specific fields in combination to ensure retrieval of requested records. You can tailor your eligibility requests to use different sets of fields depending on the application.
In some cases, search options allow you to get a successful response even without a piece of information like the memberId
. A common, name-based search option can include the firstName
, lastName
, and dateOfBirth
of the member in question.
If you always have the member ID, we suggest sending a request containing the memberId
, firstName
, lastName
, and dateOfBirth
fields.
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. The Change Healthcare API returns all information received from the trading partner in the Eligibility response.
How do Raw-X12 Eligibility requests and responses work?
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.
NOTE
Before using the Eligibility
/raw-X12
endpoint, contact your Change Healthcare 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.
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 Change Healthcare 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://apigw.changehealthcare.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
```javascript
POST /medicalnetwork/eligibility/v3/raw-x12 HTTP/1.1
Host: ${apigee_host}
Authorization: Bearer <Your-Access-Token>
Content-Type: application/json
{
"x12": "ISA*00* *01*password *ZZ*999999 *ZZ*RTEXCHANGE
*200708*0603*^*00501*123456789*0*P*:~GS*HS*999999samp*PAYERID*20200708*0603*12345678
9*X*005010X279A1~ST*270*123456789*005010X279A1~BHT*0022*13*123456789*20200708*0603~
HL*1**20*1~NM1*PR*2*Unknown*****PI*serviceId~HL*2*1*21*1~NM1*1P*2*provider_name*****XX*0123456
789~PRV*AD*PXC*54321g~HL*3*2*22*1~TRN*1*123456789*9EMDEON999~NM1*IL*1*doeOne*johnOne*
***MI*0000000000~REF*SY*555443333~REF*HJ*card123~DMG*D8*18800102*M~HL*4*3*23*0~TRN*1*
123456789*9EMDEON999~NM1*03*1*doeone*janeOne~REF*6P*1111111111~DMG*D8*18160421*F~DTP*2
91*RD8*20100101-20100102~EQ*98~SE*21*123456789~GE*1*123456789~IEA*1*123456789~"
}
```
X12 EDI 271 response
```javascript
{
"x12": "ISA*00* *01*SomePwd *ZZ* RTEXCHANGE *ZZ*999999
*201006*0641*^*00501*123456789*0*T*:~GS*HB*PAYERID*999999samp*20131015*2219*123456789*X
*005010X279A1~ST*271*946380841*005010X279A1~BHT*0022*11*123456789*20200708*0603~HL*1*
*20*1~NM1*PR*2*Unknown*****PI*PAYERID~HL*2*1*21*1~NM1*1P*2*provider_name*****XX*0123456789~
HL*3*2*22*0~TRN*1*123456789*9EMDEON999*~NM1*IL*1*doeOne*johnOne***~REF*SY*111111111~DMG*
D8*18800102*M~DTP*291*RD8*20160818-20160818~EB*1*IND*30*QM*QMB~DTP*292*RD8*20160818-
20160818~EB*R*IND*30*WA*MEDICARE PART A~DTP*291*RD8*20160818-
20160818~EB*R*IND*30*MB*MEDICARE PART B~DTP*291*RD8*20160818-
20160818~SE*19*946380841~GE*1*123456789~IEA*1*123456789~"
}
```
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 the Eligibility OpenAPI Spec for further details.
What about cases where a subscriber/patient does not have/is not covered by a medical plan/associated plan?
The following message appears when a subscriber does not have active coverage from a medical plan:
JSON Eligibility Object | Description |
---|---|
json { "errors": [ { "field": "subscriber", "description": "Invalid/Missing Subscriber/Insured Name", "followupAction": "Please Correct and Resubmit", "location": "Loop 2100C" }, { "field": "AAA", "description": "Transaction contained a AAA rejection" } ] } | The Eligibility response shows a Missing Subscriber result, indicating that they are not covered by an insurance policy. This example shows that the subscriber object contains the error in the request.Mistakes and typos in other fields in the subscriber object may trigger this error, so check all fields submitted in the subscriber object to ensure another issue did not trigger this result. |
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?
You are getting the NPI error because you sent the taxId
in the incorrect field. You sent it in the 'referenceIdentification' but you should also see the field labeled 'taxId'. If you use that field, it should work.
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?
The reassociationKey is a tracking number associated with the eligibility transaction so that we can look up the transaction being sent.
Is there a way to reduce the number of requests by clubbing the service types together? Any idea which payers allow that and which don't?
We do not know which payers allow more than one serviceType code. 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? (I know it is optional in the sandbox because I have never sent it and the calls worked). Should this field be added to the call and what are its pros and cons?
This is related to dependent's information, the following 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, coinsurance, 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 you 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? I didn't see anything here: Bare Minimum Eligibility requests.
A submitter ID is assigned to any entity submitting healthcare transactions to a payer. Basically, a submitter ID is your account number with Change Healthcare. If your child accounts are submitting healthcare transactions to a payer OR if you want to keep those sub-accounts separate, they would each get their own submitter ID as well.
Any action 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?
- Trading Partner Service ID is the Payer ID you will need to request benefit information from an insurance carrier. Here is a list of test tradingPartnerServiceId.
- ServiceType code 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 serviceType code 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 Change Health care dashboard and throws the same error. Are the any extra details do we need to send while checking eligibility for the medicare insurance?
CMSMED requires NPI enrollment before they reply to your requests. Have you enrolled any NPIs you are using in the request with CMS through the ConnectCenter and Enrollments Central?
If you are still in implementation, you can contact [email protected] for more detailed help.
Is it possible for a payer's name, Payer ID, or Eligibility ID to change in the ConnectCenter Payer List? If so, does anything happen with that change; is any kind of notification or update sent to customers?
Yes, it is not very likely but possible. Especially, if a payer is bought by another payer.
We do send out customer service announcements (CSAs) through email to customers who enroll for the notifications. Be sure to ask your implementation analyst to help you get set up for those notifications.
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 using tradingPartnerServiceId as UHC:
{
"code": "B",
"name": "Co-Payment",
"coverageLevelCode": "IND",
"coverageLevel": "Individual",
"serviceTypeCodes": [
"33"
],
"serviceTypes": [
"Chiropractic"
],
"timeQualifierCode": "7",
"timeQualifier": "Day",
"benefitAmount": "12",
"inPlanNetworkIndicatorCode": "W",
"inPlanNetworkIndicator": "Not Applicable"
},
Request: please use standard HTTP responses to indicate the result of a request. For example, a request to the Eligibility API that has multiple invalid values returns a 200 status code, but the response has an error key with details on the error fields (this should be a 400 status code to indicate issues with the request parameters). Additionally, if the Authorization header is not sent, a 400 status code is returned, although a 403 unauthorized status code would be much more clear what the issue is.
There are a few reasons for why we use the status codes we do today. For the Eligibility API, it is possible to get back errors from applications downstream of the API itself. Those might come back from Change Healthcare's clearinghouse where our payer connections are configured or from the payer. These errors would come back as 200 status because we successfully made the connection to the downstream entity and the request is being rejected by a different system.
As for the error with the missing Authorization header, I can see why a 400 Bad Request might describe the error. It is not that your authentication is invalid, but a basic requirement of the request is not being met. All requests must have the Authorization header, so any request without the header would be considered a 400 Bad Request. If you send the Authorization header with an invalid or expired token, you will receive a 401 Unauthorized.
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.
Here are some general troubleshooting tips:
- Check the headers for any typos or unexpected values.
- Validate your JSON to make sure it is properly formatted.
- Try the
healthcheck
endpoint to make sure the API is up and running. - Check out our pre-formatted Postman collections in the documentation to compare values and troubleshoot differences.
If you still experience issues, send over the headers and body of the request, and we will troubleshoot in depth.
How can I interpret the following?
- How would you interpret this service level info from sandbox response?
{
"code": "C",
"name": "Deductible",
"serviceTypeCodes": [
"45",
"42"
],
"serviceTypes": [
"Hospice",
"Home Health Care"
],
"insuranceTypeCode": "MA",
"insuranceType": "Medicare Part A",
"timeQualifierCode": "26",
"timeQualifier": "Episode",
"benefitAmount": "0",
"benefitsDateInformation": {
"benefit": "20170101-20171231"
}
},
How do I interpret "329 days" here in terms of co-payment?
{
"code": "B",
"name": "Co-Payment",
"serviceTypeCodes": [
"30"
],
"serviceTypes": [
"Health Benefit Plan Coverage"
],
"insuranceTypeCode": "MA",
"insuranceType": "Medicare Part A",
"timeQualifierCode": "7",
"timeQualifier": "Day",
"benefitAmount": "329",
"benefitsDateInformation": {
"admission": "20170101-20171231"
},
"benefitsServiceDelivery": [
{
"unitForMeasurementCode": "Days",
"timePeriodQualifierCode": "30",
"timePeriodQualifier": "Exceeded",
"numOfPeriods": "60",
"unitForMeasurementQualifierCode": "DA",
"unitForMeasurementQualifier": "Days"
},
{
"unitForMeasurementCode": "Days",
"timePeriodQualifierCode": "31",
"timePeriodQualifier": "Not Exceeded",
"numOfPeriods": "90",
"unitForMeasurementQualifierCode": "DA",
"unitForMeasurementQualifier": "Days"
},
{
"timePeriodQualifierCode": "26",
"timePeriodQualifier": "Episode",
"numOfPeriods": "1"
}
]
},
- In the preceding code snippet, does it mean that "0 episodes" come under deductible, that is, they are fully covered by insurance?
The following information is from the documentation.
Answer for # 1. — the 'Episode' is the episode of care and '26' is the number of days in that episode.
Answer for #2. — $329 is the benefit amount.
Benefits, Time Periods, and Coverage Amounts
Every Service Type segment has more or less the same format:
"serviceTypes": [ "Skilled Nursing Care" ], "insuranceTypeCode": "MA", "insuranceType": "Medicare Part A", "timeQualifierCode": "7", "timeQualifier": "Day", "benefitAmount": "164.5", "benefitsDateInformation": { "admission": "20170101-20171231" } | Note the repetition of insuranceTypeCode. Here, it is called out to identify the insurance coverage for each individual service. This value can differ from the umbrella insuranceTypeCode value; in this case the umbrella insurance code is QM for a qualified Medicare beneficiary, and the service's insuranceTypeCode is MA for Medicare Part A. The timequalifierCode shows the benefit billing period, which is Daily, using 7 as the EDI value (this value does NOT define a weekly time span). Our API provides the timeQualifier description, which is day, so benefit coverage is tracked daily. The benefitAmount is added based on the timeQualifier, so the daily benefit amount of the Skilled Nursing Care service is $164.50. |
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 Change Healthcare covers 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 Change Healthcare gives 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 Change Healthcare 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?
ServiceTypeCodes are used to identify business groupings for healthcare services and benefits. Include the serviceTypeCode in the API request call. The serviceType code consists of value and valueType. An example:
"service": {
"codes": [
{
"value": "98",
"valueType": "ServiceTypeCode"
}
Each payer may have different supported service types for eligibility and benefit inquiries. You may visit individual payer site to find supported serviceType codes and the serviceType code best to use for the procedure you or your patients are trying to get an estimate of out-of-pocket cost. We recommend you purchase and use the 270 Implementation Guide specs.
Or
List of serviceType codes you can find on Connect Center >> under Verification >> New Eligibility Request >> drop-down list under ‘Service Information’ >> Service Type.
If you are not sure what service type code to use, you can use serviceType code “30” for a general Health Benefit Plan Coverage inquiry.
Here is a list of official list from the x12 org.
NOTE
Only serviceType codes with Starting date: 09/20/2009 will be active.
In the /WebMD_Eligibility_002/Request_HTML.aspx
endpoint, how do we know about the Annual Maximum using API, how do we know about the Benefits Remaining using API, how do we know about the Deductible Remaining using API?
/WebMD_Eligibility_002/Request_HTML.aspx
endpoint, how do we know about the Annual Maximum using API, how do we know about the Benefits Remaining using API, how do we know about the Deductible Remaining using API?Our Eligibility API provides you the connectivity to our medical network where we will send your request to the payer, when the payer responds, we will send that information back to you.
- Visit.
- Click the API References tab and click Eligibility and Claims in the left navigation.
- Click the Eligibility API hyperlink.
- Clicking the Guides tab provides you documentation and information on our APIs.
- Scroll down to the Medical Network Eligibility V3 section.
- Click Eligibility V3 Getting Started — this shows the contents of request and response.
You can view the financial information (deductibles, copays, coinsurance).
Find more information here.
Does Change Healthcare 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 serviceType code, typically brings back all the benefit information for a patient.
There is also a list of serviceType codes you can refer here. MH is another serviceType code 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. Change Healthcare 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 Service Type Codes. 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 you, 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 Change Healthcare would look into the feasibility of a connection being made to that payer.
If you are not contracted with Change Healthcare, 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.
- Go to Payer Tools >> Payer Search.
- Select the associated products and click search.
- 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?
- You can submit a new payer connection request through ConnectCenter >> Payer Tools > Payer Search.
- If you search for your company at the top of screen, the "to request a connection to a payer not on the list below, please submit a New Payer Connection Request." shows. Click the New Payer Connection Request. This will be routed to our payer implementations team for review.
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 insuranceTypes, which allows you to determine if the benefits apply to Part A, Part B, or another insurance. Here is a sample response that contains this information:
},
"controlNumber": "123456789",
"reassociationKey": "123456789",
"tradingPartnerServiceId": "CMSMED",
"provider": {
"providerName": "HAPPY DOCTORS GROUP PRACTICE",
"entityIdentifier": "Provider",
"entityType": "Non-Person Entity",
"npi": "1234567893"
},
"subscriber": {
"memberId": "0000000000",
"firstName": "JOHNONE",
"lastName": "DOEONE",
"middleName": "M",
"gender": "F",
"entityIdentifier": "Insured or Subscriber",
"entityType": "Person",
"dateOfBirth": "18800102",
"relationToSubscriber": "Self",
"insuredIndicator": "Y",
"maintenanceTypeCode": "001",
"maintenanceReasonCode": "25",
"address": {
"address1": "123 address1",
"city": "SEATTLE",
"state": "WA",
"postalCode": "981010000"
}
},
"subscriberTraceNumbers": [
{
"traceTypeCode": "2",
"traceType": "Referenced Transaction Trace Numbers",
"referenceIdentification": "123456789",
"originatingCompanyIdentifier": "9877281234"
},
{
"traceTypeCode": "2",
"traceType": "Referenced Transaction Trace Numbers",
"referenceIdentification": "123456789",
"originatingCompanyIdentifier": "9877281234"
}
],
"payer": {
"entityIdentifier": "Payer",
"entityType": "Non-Person Entity",
"name": "CMS",
"payorIdentification": "CMSMED"
},
"planDateInformation": {
"eligibility": "20211020-20211020"
},
"planStatus": [
{
"statusCode": "1",
"status": "Active Coverage",
"serviceTypeCodes": [
"88",
"30",
"42",
"45",
"48",
"49",
"69",
"76",
"83",
"A5",
"A7",
"AG",
"BT",
"BU",
"BV",
"30",
"2",
"23",
"24",
"25",
"26",
"27",
"28",
"3",
"33",
"36",
"37",
"38",
"39",
"4",
"40",
"42",
"50",
"51",
"52",
"53",
"62",
"67",
"69",
"73",
"76",
"83",
"86",
"98",
"A4",
"A6",
"A8",
"AI",
"AJ",
"AK",
"AL",
"BT",
"BU",
"BV",
"DM",
"UC"
]
}
],
"benefitsInformation": [
{
"code": "I",
"name": "Non-Covered",
"serviceTypeCodes": [
"41",
"54"
],
"serviceTypes": [
"Routine (Preventive) Dental",
"Long Term Care"
]
},
{
"code": "1",
"name": "Active Coverage",
"serviceTypeCodes": [
"88"
],
"serviceTypes": [
"Pharmacy"
]
},
{
"code": "1",
"name": "Active Coverage",
"serviceTypeCodes": [
"30",
"42",
"45",
"48",
"49",
"69",
"76",
"83",
"A5",
"A7",
"AG",
"BT",
"BU",
"BV"
],
"serviceTypes": [
"Health Benefit Plan Coverage",
"Home Health Care",
"Hospice",
"Hospital - Inpatient",
"Hospital - Room and Board",
"Maternity",
"Dialysis",
"Infertility",
"Psychiatric - Room and Board",
"Psychiatric - Inpatient",
"Skilled Nursing Care",
"Gynecological",
"Obstetrical",
"Obstetrical/Gynecological"
],
"insuranceTypeCode": "MA",
"insuranceType": "Medicare Part A",
"benefitsDateInformation": {
"plan": "20041101"
},
"additionalInformation": [
{
"description": "0-Beneficiary insured due to age OASI"
}
]
},
{
"code": "C",
"name": "Deductible",
"serviceTypeCodes": [
"30"
],
"serviceTypes": [
"Health Benefit Plan Coverage"
],
"insuranceTypeCode": "MA",
"insuranceType": "Medicare Part A",
"timeQualifierCode": "26",
"timeQualifier": "Episode",
"benefitAmount": "1484",
"benefitsDateInformation": {
"plan": "20210101-20211231"
}
},
{
"code": "C",
"name": "Deductible",
"serviceTypeCodes": [
"30"
],
"serviceTypes": [
"Health Benefit Plan Coverage"
],
"insuranceTypeCode": "MA",
"insuranceType": "Medicare Part A",
"timeQualifierCode": "29",
"timeQualifier": "Remaining",
"benefitAmount": "1484",
"benefitsDateInformation": {
"plan": "20210101-20211231"
}
},
{
"code": "C",
"name": "Deductible",
"serviceTypeCodes": [
"42",
"45"
],
"serviceTypes": [
"Home Health Care",
"Hospice"
],
"insuranceTypeCode": "MA",
"insuranceType": "Medicare Part A",
"timeQualifierCode": "26",
"timeQualifier": "Episode",
"benefitAmount": "0",
"benefitsDateInformation": {
"benefit": "20210101-20211231"
}
},
{
"code": "1",
"name": "Active Coverage",
"serviceTypeCodes": [
"30",
"2",
"23",
"24",
"25",
"26",
"27",
"28",
"3",
"33",
"36",
"37",
"38",
"39",
"4",
"40",
"42",
"50",
"51",
"52",
"53",
"62",
"67",
"69",
"73",
"76",
"83",
"86",
"98",
"A4",
"A6",
"A8",
"AI",
"AJ",
"AK",
"AL",
"BT",
"BU",
"BV",
"DM",
"UC"
],
"serviceTypes": [
"Health Benefit Plan Coverage",
"Surgical",
"Diagnostic Dental",
"Periodontics",
"Restorative",
"Endodontics",
"Maxillofacial Prosthetics",
"Adjunctive Dental Services",
"Consultation",
"Chiropractic",
"Dental Crowns",
"Dental Accident",
"Orthodontics",
"Prosthodontics",
"Diagnostic X-Ray",
"Oral Surgery",
"Home Health Care",
"Hospital - Outpatient",
"Hospital - Emergency Accident",
"Hospital - Emergency Medical",
"Hospital - Ambulatory Surgical",
"MRI/CAT Scan",
"Smoking Cessation",
"Maternity",
"Diagnostic Medical",
"Dialysis",
"Infertility",
"Emergency Services",
"Professional (Physician) Visit - Office",
"Psychiatric",
"Psychotherapy",
"Psychiatric - Outpatient",
"Substance Abuse",
"Alcoholism",
"Drug Addiction",
"Vision (Optometry)",
"Gynecological",
"Obstetrical",
"Obstetrical/Gynecological",
"Durable Medical Equipment",
"Urgent Care"
],
"insuranceTypeCode": "MB",
"insuranceType": "Medicare Part B",
"benefitsDateInformation": {
"plan": "20041101"
},
"additionalInformation": [
{
"description": "0-Beneficiary insured due to age OASI"
}
]
},
{
"code": "C",
"name": "Deductible",
"serviceTypeCodes": [
"30"
],
"serviceTypes": [
"Health Benefit Plan Coverage"
],
"insuranceTypeCode": "MB",
"insuranceType": "Medicare Part B",
"timeQualifierCode": "23",
"timeQualifier": "Calendar Year",
"benefitAmount": "203",
"benefitsDateInformation": {
"plan": "20210101-20211231"
}
},
{
"code": "C",
"name": "Deductible",
"serviceTypeCodes": [
"30"
],
"serviceTypes": [
"Health Benefit Plan Coverage"
],
"insuranceTypeCode": "MB",
"insuranceType": "Medicare Part B",
"timeQualifierCode": "29",
"timeQualifier": "Remaining",
"benefitAmount": "0",
"benefitsDateInformation": {
"plan": "20210101-20211231"
}
},
{
"code": "A",
"name": "Co-Insurance",
"serviceTypeCodes": [
"30"
],
"serviceTypes": [
"Health Benefit Plan Coverage"
],
"insuranceTypeCode": "MB",
"insuranceType": "Medicare Part B",
"timeQualifierCode": "27",
"timeQualifier": "Visit",
"benefitPercent": "0.2",
"benefitsDateInformation": {
"plan": "20210101-20211231"
}
},
{
"code": "C",
"name": "Deductible",
"serviceTypeCodes": [
"42",
"67",
"AJ"
],
"serviceTypes": [
"Home Health Care",
"Smoking Cessation",
"Alcoholism"
],
"insuranceTypeCode": "MB",
"insuranceType": "Medicare Part B",
"timeQualifierCode": "23",
"timeQualifier": "Calendar Year",
"benefitAmount": "0",
"benefitsDateInformation": {
"benefit": "20210101-20211231"
}
},
{
"code": "A",
"name": "Co-Insurance",
"serviceTypeCodes": [
"42",
"67",
"AJ"
],
"serviceTypes": [
"Home Health Care",
"Smoking Cessation",
"Alcoholism"
],
"insuranceTypeCode": "MB",
"insuranceType": "Medicare Part B",
"timeQualifierCode": "27",
"timeQualifier": "Visit",
"benefitPercent": "0",
"benefitsDateInformation": {
"benefit": "20210101-20211231"
}
},
{
"code": "R",
"name": "Other or Additional Payor",
"serviceTypeCodes": [
"88"
],
"serviceTypes": [
"Pharmacy"
],
"insuranceTypeCode": "OT",
"insuranceType": "Other",
"headerLoopIdentifierCode": "2120",
"trailerLoopIdentifierCode": "2120",
"benefitsAdditionalInformation": {
"planNumber": "S5601",
"planNetworkIdNumber": "203"
},
"benefitsDateInformation": {
"benefit": "20210101"
},
"benefitsRelatedEntity": {
"entityIdentifier": "Payer",
"entityType": "Non-Person Entity",
"entityName": "extra healthy insurance",
"address": {
"address1": "123 address1",
"city": "Nashville",
"state": "TN",
"postalCode": "37203"
},
"contactInformation": {
"contacts": [
{
"communicationMode": "Telephone",
"communicationNumber": "0000000000"
},
{
"communicationMode": "Uniform Resource Locator (URL)",
"communicationNumber": "www.testwebsite.com"
}
]
}
},
"benefitsRelatedEntities": [
{
"entityIdentifier": "Payer",
"entityType": "Non-Person Entity",
"entityName": "extra healthy insurance",
"address": {
"address1": "123 address1"
},
"contactInformation": {
"contacts": [
{
"communicationMode": "Telephone",
"communicationNumber": "0000000000"
},
{
"communicationMode": "Uniform Resource Locator (URL)",
"communicationNumber": "www.testwebsite.com"
}
]
}
}
]
}
],
"x12": "ISA*00* *01*SomePwd *ZZ*EMDEON *ZZ*TPG00000 *230808*1017*^*00501*123456789*0*T*:~GS*HB*MTEXE*LLX1210001*20131015*2219*123456789*X*005010X279A1~ST*271*0001*005010X279A1~BHT*0022*11*a3ccf869-a31b-ddf0-c3ed-876557226558*20230808*1017~HL*1**20*1~NM1*PR*2*CMS*****PI*CMSMED~HL*2*1*21*1~NM1*1P*2*HAPPY DOCTORS GROUP PRACTICE*****XX*1234567893~HL*3*2*22*0~TRN*2*123456789*9877281234~TRN*2*1266798199*9MCK-TSHRT~NM1*IL*1*DOEONE*JOHNONE*M***MI*0000000000~N3*123 address1~N4*SEATTLE*WA*981010000~DMG*D8*18800102*F~INS*Y*18*001*25~DTP*307*RD8*20211020-20211020~EB*I**41^54~EB*1**88~EB*1**30^42^45^48^49^69^76^83^A5^A7^AG^BT^BU^BV*MA~DTP*291*D8*20041101~MSG*0-Beneficiary insured due to age OASI~EB*C**30*MA**26*1484~DTP*291*RD8*20210101-20211231~EB*C**30*MA**29*1484~DTP*291*RD8*20210101-20211231~EB*C**42^45*MA**26*0~DTP*292*RD8*20210101-20211231~EB*1**30^2^23^24^25^26^27^28^3^33^36^37^38^39^4^40^42^50^51^52^53^62^67^69^73^76^83^86^98^A4^A6^A8^AI^AJ^AK^AL^BT^BU^BV^DM^UC*MB~DTP*291*D8*20041101~MSG*0-Beneficiary insured due to age OASI~EB*C**30*MB**23*203~DTP*291*RD8*20210101-20211231~EB*C**30*MB**29*0~DTP*291*RD8*20210101-20211231~EB*A**30*MB**27**0.2~DTP*291*RD8*20210101-20211231~EB*C**42^67^AJ*MB**23*0~DTP*292*RD8*20210101-20211231~EB*A**42^67^AJ*MB**27**0~DTP*292*RD8*20210101-20211231~EB*R**88*OT~REF*18*S5601~REF*N6*203*SilverScript SmartRx~DTP*292*D8*20210101~LS*2120~NM1*PR*2*extra healthy insurance~N3*123 address1~N4*Nashville*TN*37203~PER*IC**TE*0000000000*UR*www.testwebsite.com~LE*2120~SE*50*0001~GE*1*123456789~IEA*1*123456789~"
}
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.
Related Topics
Updated 3 months ago