Eligibility API 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 does a typical Eligibility API request look like?

The Eligibility API uses a POST HTTPS 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. Here is a 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.

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.

```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 numerous 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 Eligibility requests, you will see the value of 30, for Health Benefit Plan Coverage. Some payers typically give a 30 code 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 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 in the Eligibility response.

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

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's 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, then 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 along with other insurance benefits, for a subscriber, or dependents of the subscriber, on 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 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, taken 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 can't 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 they 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 purposes of a medical claim.

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

{
    "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. The preceding 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 make sure another issue did not trigger this result.


Did this page help you?