Eligibility v3

Summary API Attachments FAQ CHANGE LOG   
awss
  

Overview

The Eligibility API 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.

We also 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.

Our Eligibility API solution provides complete patient profile and benefits information, to support health care 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.

API Onboarding

Most of our APIs are private and require credentials to gain access. Begin by obtaining your client_id and client_secret for our sandbox test environment. (Contact your Change Healthcare representative if you do not have this information.)

You will also use a separate Change Healthcare-issued credential pair for your production API work.

You can test the APIs from within our interactive documentation, use an application such as Postman, or use your own development platform. You use a separate Change Healthcare-issued secret pair for your production API work.

Try our Postman Collection! Run in Postman

API Endpoints

The endpoints for the Eligibility API collection are as follows.

  • This is the primary Eligibility verification API endpoint:

    https://apis.changehealthcare.com/medicalnetwork/eligibility/v3/

  • The Eligibility collection also provides a GET /healthcheck call to check that the service you're trying to use is up and running:

    https://apis.changehealthcare.com/medicalnetwork/eligibility/v3/healthcheck

  • Each of our API collections also contains an endpoint for obtaining new authorization tokens:

    https://apis.changehealthcare.com/apip/auth/v2/token

Raw-X12 EDI Support

We also support a traditional X12 EDI 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.

  • The Eligibility Raw-X12 endpoint is as follows:

    https://apis.changehealthcare.com/medicalnetwork/eligibility/v3/raw-x12

For further details about Eligibility API usage, see the FAQ page.

Using the API

In our interactive documentation, select the API tab, and select the green POST API object. Scroll down to the Authorization field, enter the word Bearer, and paste your token into the Bearer Token field.

If you are using our Postman collection or a similar development console, ensure your client_id and client_secret for your production account are installed in your Authorization API's request body, or that you set up your environment variables to refer to these credentials whenever you require a token. If you correctly set up your environment variables, you can install the collection in Postman (for example), and simply run the Authorization API to obtain a token, which will automatically be used by the other APIs in the collection.

For Sandbox and production API testing, you can also edit the request body. Do not use real-world values in Sandbox API usage. Doing so will produce errors.

We provide a list of Medical Service ID test values to use in Sandbox so you can get a variety of different responses. See the Eligibility Sandbox Test Responses document located in the Attachments tab.

For Sandbox usage, we also provide predefined values to simulate Personal Medical Information (PMI) in the Sandbox environment. For successful use of Sandbox APIs, you must use these "fake patient" values for your testing. Consult the Sandbox Test PMI Values document located in the Attachments tab.

For further details about Eligibility API usage, see the FAQ page.

Links to Eligibility FAQ Topics

You'll find the following topics on this page:

Accessing the Eligibility APIs

How do I access the Production APIs?

What are the endpoints for getting authorization tokens?

What information needs to go in the API Request header?

Using the Sandbox environment

Do you have a sandbox that I can test before signing a contract?

How do I access the Sandbox environment?

Sandbox predefined fields and values

Using the Eligibility APIs

What does a typical API request look like?

What does a typical API response look like?

How do Raw-X12 Eligibility requests and responses work?

Understanding API features

Using Mandatory Fields and Predefined Values

Fields in the requests object

Fields in the provider object

Fields in the subscriber and dependents objects

Fields in the encounter object

Eligibility API enrollment requirements

What are some typical Errors and Error codes?

Accessing the Eligibility APIs

How do I access the Production APIs?

For the Change Healthcare Medical Network Eligibility API, the endpoint is:

https://apis.changehealthcare.com/medicalnetwork/eligibility/v3/

Eligibility also offers a Healthcheck API, with which you can check the operating status of the cloud-based API engine:

https://apis.changehealthcare.com//medicalnetwork/eligibility/v3/healthcheck

What are the endpoints for getting authorization tokens?

The endpoint URL for authorization tokens is as follows:

https://apis.changehealthcare.com/apip/auth/v2/token/

Bearer tokens have a two-hour lifespan (7200 seconds) in production.

Find out more about our security protocols in the Security -> Authorization section of this portal.

What information needs to go in the API Request header?

The Eligibility API request header needs an authorization token. You can get the token by making an API call to:

curl -X POST \
  'https://sandbox.apis.changehealthcare.com/apip/auth/v2/token' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_id": "<Your-ClientId>",
  "client_secret": "<Your-ClientSecret>",
  "grant_type": "client_credentials"
}'

The authorization token is a requirement for making an Eligibility API call, which will have the following headers:

Content-Type: application/json
Authorization: Bearer <Your-Access-Token>

In production, the lifespan of a token is two hours (7200 seconds). For Sandbox use, a token lifespan is one hour.

Using the Sandbox environment

Do you have a sandbox that I can test before signing a contract?

We do! You can use our Sandbox environment even before signing a contract. It requires a separate set of secure credentials which you can obtain from your Change Healthcare representative. After receiving your client_id and client_secret for our Sandbox environment, you can test the API in our interactive documentation, use an application such as Postman, or test APIs using your own development console.

Try our Postman Collection! Run in Postman

We have a list of test service ID values to use in Sandbox for testing a variety of different responses. See the section Sandbox predefined fields and values below.

How do I access the Sandbox environment?

The Sandbox endpoint URL for authorization tokens is as follows:

https://sandbox.apis.changehealthcare.com/apip/auth/v2/token/

Authorization tokens have a lifespan of 3600 seconds (1 hour) in the Sandbox environment.

For testing, the Sandbox Eligibility API endpoint is as follows:

https://sandbox.apis.changehealthcare.com/medicalnetwork/eligibility/v3/

The Healthcheck Sandbox URL for this API set is as follows:

https://sandbox.apis.changehealthcare.com//medicalnetwork/eligibility/v3/healthcheck

Sandbox predefined fields and values

You can edit fields in the HTTP request body to see how the API works with changes to the data. For Sandbox use, you are limited to a specific set of values.

We provide predefined values to simulate Personal Medical Information (PMI) in the Sandbox environment. If you haven't seen these before, consult the Sandbox Test PMI Values document located in the Attachments tab.

Any field listed for the API can appear at any level of the request model. For Sandbox usage, all fields must have the correct predefined values to obtain a successful response. Inventing new PMI values or using real-world PMI values will result in errors such as the messages listed below.

The following fields must use one of the following predefined values.

Field Values
memberId "0000000000", "0000000001", "0000000002", "1234567890", "0000000004", "0000000005", "0000000006","0000000007", "123456789"
firstName "johnone", "johntwo", "janeone", "janetwo"
lastName "doeone", "doetwo"
middleName "middleone", "middletwo"
gender "m", "u", "f"
dateOfBirth "18800102", "18800101", "18160421", "19800101", "19800102", "20000101", "20000102"
ssn "000000000", "555443333", "1111111111", "000000001", "891234567", "123456789"
groupNumber "0000000000", "1111111111","1234567891","0000000001", "0000000002", "0000000003", "0000000004", "0000000005"
address1 "123 address1", "000 address1"
address2 "apt 123", "apt 000", "123", "000"
city "city1", "city2"
state "wa", "tn"
postalCode "981010000", "372030000"
employerId "00000", "12345","00001","00002","000000000", "123456789","123456"
propertyCasualtyClaimNumber "00000", "12345","00001","00002"
patientControlNumber "00000", "12345","00001","00002"
priorAuthorizationNumber "00000", "12345","00001","00002"
referralNumber "00000", "12345","00001","00002"
repricedClaimNumber "00000", "12345","00001","00002"
investigationalDeviceExemptionNumber "00000", "12345","00001","00002"
claimNumber "00000", "12345","00001","00002"
name "johnone doeone", "johntwo doetwo", "janeone doeone", "janetwo doetwo", "submitter contact info"
phoneNumber "0000000000", "123456789", "0000000001", "0000000002"
faxNumber "0000000000", "123456789", "0000000001", "0000000002"
email "email@email.com", "email@email.net"
stateLicenseNumber "0000000", "0000001", "123456"
contractVersionIdentifier "111111", "222222", "123456"
patientControlNumber "00000", "12345","00001","00002"
priorAuthorizationNumber "00000", "12345","00001","00002"
referralNumber "00000", "12345","00001","00002"
claimControlNumber "00000", "12345","00001","00002"
cliaNumber "12D4567890", "00D0000001"
repricedClaimNumber "00000", "12345","00001","00002"
mammographyCertificationNumber "00000", "12345","00001","00002"
medicalRecordNumber "00000", "12345","00001","00002"
demoProjectIdentifier "00000", "12345","00001","00002"
carePlanOversightNumber "00000", "12345","00001","00002"
policyNumber "00000", "12345","00001","00002"
npi "1760854442", "1942788757"
organizationName "happy doctors group", "happy doctors grouppractice","extra healthy insurance", "regional ppo network"

Note: tradingPartnerServiceId 9496 is a test payer and is the only payer that we allow for use in Sandbox.

If you don't use the predefined values, you will receive errors like the following:

{
    "errors": [
        {
            "field": "claimInformation.claimSupplementalInformation",
            "description": "Please use predefined canned users for non-prod environments: claimNumber was not predefined."
        },
        {
            "field": "subscriber",
            "description": "Please use predefined canned users for non-prod environments: policyNumber was not predefined."
        },
        {
            "field": "claimInformation",
            "description": "Please use predefined canned users for non-prod environments: patientControlNumber was not predefined."
        },
        {
            "field": "providers[0]",
            "description": "Please use predefined canned users for non-prod environments: employerId was not predefined."
        },
        {
            "field": "providers[1]",
            "description": "Please use predefined canned users for non-prod environments: lastName was not predefined."
        },
        {
            "field": "subscriber.address",
            "description": "Please use predefined canned users for non-prod environments: city was not predefined."
        },
        {
            "field": "providers[0].address",
            "description": "Please use predefined canned users for non-prod environments: city was not predefined."
        },
        {
            "field": "providers[0].contactInformation",
            "description": "Please use predefined canned users for non-prod environments: phoneNumber was not predefined."
        },
        {
            "field": "claimInformation.serviceFacilityLocation.address",
            "description": "Please use predefined canned users for non-prod environments: city was not predefined."
        },
        {
            "field": "dependent.address",
            "description": "Please use predefined canned users for non-prod environments: city was not predefined."
        },
        {
            "field": "providers[2]",
            "description": "Please use predefined canned users for non-prod environments: lastName was not predefined."
        }
    ]
}

Using the Eligibility APIs

What does a typical API request look like?

The Eligibility API uses a POST HTTPS call. You can provide the input as JSON in the body of the request:

POST /medicalnetwork/eligibility/v3 HTTP/1.1
Host: sandbox.apis.changehealthcare.com
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"
    ]
  }
}

What does a typical API response look like?

Responses to our Medical Network APIs can be lengthy due to the many data points that a payer or trading partner provides in the query response. Our APIs translate back and forth between JSON and X12 EDI when the information departs into and returns from the medical network. We also support Raw X12 APIs should you wish to directly communicate using that data format.

{
    "controlNumber": "123456789",
    "tradingPartnerServiceId": "AETNX",
    "provider": {
        "providerName": "Main Street Primary Care",
        "npi": "0123456789"
    },
    "subscriber": {
        "memberId": "1234567890",
        "firstName": "joe",
        "lastName": "smoe",
        "groupNumber": "111111111111111",
        "address": {
            "address1": "17 cherry tree lane",
            "address2": "",
            "city": "seattle",
            "state": "wa",
            "postalCode": "98101"
        }
    },
    "dependents": [
        {
            "memberId": "1234567890",
            "firstName": "joe",
            "lastName": "smoe",
            "gender": "M",
            "dateOfBirth": "19800101",
            "relationToSubscriber": "Spouse",
            "relationToSubscriberCode": "01",
            "address": {
                "address1": "17 cherry tree lane",
                "address2": "",
                "city": "seattle",
                "state": "wa",
                "postalCode": "98101"
            }
        }
    ],
    "planInformation": {
        "planNumber": "1111111",
        "groupNumber": "111111111111111"
    },
    "planDateInformation": {
        "planBegin": "20140601",
        "eligibilityBegin": "20140601",
        "service": "20170105"
    },
    "planStatus": [
        {
            "statusCode": "1",
            "status": "Active Coverage",
            "planDetails": "Open POS Plus",
            "serviceTypeCodes": [
                "30",
                "80"
            ]
        }
    ],
    "benefitsInformation": [
        {
            "code": "L",
            "name": "Primary Care Provider",
            "coverageLevelCode": "ESP",
            "coverageLevel": "Employee and Spouse",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "insuranceTypeCode": "PS",
            "insuranceType": "Point of Service (POS)",
            "additionalInformation": [
                {
                    "description": "PCP SELECTION NOT REQUIRED"
                }
            ]
        },
        {
            "code": "W",
            "name": "Other Source of Data",
            "benefitsRelatedEntity": {
                "entityIdentifier": "Payer",
                "entityType": "Non-Person Entity",
                "entityName": "Test Health",
                "address": {
                    "address1": "Test PO Box",
                    "city": "Test City",
                    "state": "KY",
                    "postalCode": "11111"
                }
            }
        },
        {
            "code": "1",
            "name": "Active Coverage",
            "coverageLevelCode": "ESP",
            "coverageLevel": "Employee and Spouse",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "insuranceTypeCode": "PS",
            "insuranceType": "Point of Service (POS)",
            "planCoverage": "Open POS Plus"
        },
        {
            "code": "C",
            "name": "Deductible",
            "coverageLevelCode": "FAM",
            "coverageLevel": "Family",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "timeQualifierCode": "23",
            "timeQualifier": "Calendar Year",
            "benefitAmount": "1200",
            "inPlanNetworkIndicatorCode": "Y",
            "inPlanNetworkIndicator": "Yes",
            "benefitsDateInformation": {
                "planBegin": "20170101"
            },
            "additionalInformation": [
                {
                    "description": "Med Dent"
                },
                {
                    "description": "All Other In-Network Providers"
                }
            ]
        },
        {
            "code": "C",
            "name": "Deductible",
            "coverageLevelCode": "FAM",
            "coverageLevel": "Family",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "timeQualifierCode": "29",
            "timeQualifier": "Remaining",
            "benefitAmount": "1200",
            "inPlanNetworkIndicatorCode": "Y",
            "inPlanNetworkIndicator": "Yes",
            "additionalInformation": [
                {
                    "description": "Med Dent"
                }
            ]
        },
        {
            "code": "C",
            "name": "Deductible",
            "coverageLevelCode": "IND",
            "coverageLevel": "Individual",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "timeQualifierCode": "23",
            "timeQualifier": "Calendar Year",
            "benefitAmount": "600",
            "inPlanNetworkIndicatorCode": "Y",
            "inPlanNetworkIndicator": "Yes",
            "benefitsDateInformation": {
                "planBegin": "20170101"
            },
            "additionalInformation": [
                {
                    "description": "Med Dent"
                },
                {
                    "description": "All Other In-Network Providers"
                }
            ]
        },
        {
            "code": "C",
            "name": "Deductible",
            "coverageLevelCode": "IND",
            "coverageLevel": "Individual",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "timeQualifierCode": "29",
            "timeQualifier": "Remaining",
            "benefitAmount": "600",
            "inPlanNetworkIndicatorCode": "Y",
            "inPlanNetworkIndicator": "Yes",
            "additionalInformation": [
                {
                    "description": "Med Dent"
                }
            ]
        },
        {
            "code": "G",
            "name": "Out of Pocket (Stop Loss)",
            "coverageLevelCode": "IND",
            "coverageLevel": "Individual",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "benefitAmount": "3000",
            "inPlanNetworkIndicatorCode": "Y",
            "inPlanNetworkIndicator": "Yes",
            "additionalInformation": [
                {
                    "description": "All Other In-Network Providers"
                },
                {
                    "description": "INT MED AND RX"
                }
            ]
        },
        {
            "code": "G",
            "name": "Out of Pocket (Stop Loss)",
            "coverageLevelCode": "IND",
            "coverageLevel": "Individual",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "timeQualifierCode": "29",
            "timeQualifier": "Remaining",
            "benefitAmount": "2997.46",
            "inPlanNetworkIndicatorCode": "Y",
            "inPlanNetworkIndicator": "Yes"
        },
        {
            "code": "G",
            "name": "Out of Pocket (Stop Loss)",
            "coverageLevelCode": "FAM",
            "coverageLevel": "Family",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "benefitAmount": "6000",
            "inPlanNetworkIndicatorCode": "Y",
            "inPlanNetworkIndicator": "Yes",
            "additionalInformation": [
                {
                    "description": "All Other In-Network Providers"
                },
                {
                    "description": "INT MED AND RX"
                }
            ]
        },
        {
            "code": "G",
            "name": "Out of Pocket (Stop Loss)",
            "coverageLevelCode": "FAM",
            "coverageLevel": "Family",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "timeQualifierCode": "29",
            "timeQualifier": "Remaining",
            "benefitAmount": "5997.46",
            "inPlanNetworkIndicatorCode": "Y",
            "inPlanNetworkIndicator": "Yes"
        },
        {
            "code": "C",
            "name": "Deductible",
            "coverageLevelCode": "FAM",
            "coverageLevel": "Family",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "timeQualifierCode": "23",
            "timeQualifier": "Calendar Year",
            "benefitAmount": "2400",
            "inPlanNetworkIndicatorCode": "N",
            "inPlanNetworkIndicator": "No",
            "benefitsDateInformation": {
                "planBegin": "20170101"
            },
            "additionalInformation": [
                {
                    "description": "Med Dent"
                },
                {
                    "description": "DED INCLUDED IN OOP"
                },
                {
                    "description": "Flu Vaccine by Primary Care Physician in Office"
                },
                {
                    "description": "Flu Vaccine by Primary Care Physician"
                },
                {
                    "description": "Flu Vaccine by Primary Care Physician in Office"
                },
                {
                    "description": "Flu Vaccine"
                }
            ]
        },
        {
            "code": "C",
            "name": "Deductible",
            "coverageLevelCode": "FAM",
            "coverageLevel": "Family",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "timeQualifierCode": "29",
            "timeQualifier": "Remaining",
            "benefitAmount": "2400",
            "inPlanNetworkIndicatorCode": "N",
            "inPlanNetworkIndicator": "No",
            "additionalInformation": [
                {
                    "description": "Med Dent"
                }
            ]
        },
        {
            "code": "C",
            "name": "Deductible",
            "coverageLevelCode": "IND",
            "coverageLevel": "Individual",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "timeQualifierCode": "23",
            "timeQualifier": "Calendar Year",
            "benefitAmount": "1200",
            "inPlanNetworkIndicatorCode": "N",
            "inPlanNetworkIndicator": "No",
            "benefitsDateInformation": {
                "planBegin": "20170101"
            },
            "additionalInformation": [
                {
                    "description": "Med Dent"
                },
                {
                    "description": "DED INCLUDED IN OOP"
                },
                {
                    "description": "Flu Vaccine by Primary Care Physician in Office"
                },
                {
                    "description": "Flu Vaccine by Primary Care Physician"
                },
                {
                    "description": "Flu Vaccine by Primary Care Physician in Office"
                },
                {
                    "description": "Flu Vaccine"
                }
            ]
        },
        {
            "code": "C",
            "name": "Deductible",
            "coverageLevelCode": "IND",
            "coverageLevel": "Individual",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "timeQualifierCode": "29",
            "timeQualifier": "Remaining",
            "benefitAmount": "1200",
            "inPlanNetworkIndicatorCode": "N",
            "inPlanNetworkIndicator": "No",
            "additionalInformation": [
                {
                    "description": "Med Dent"
                }
            ]
        },
        {
            "code": "G",
            "name": "Out of Pocket (Stop Loss)",
            "coverageLevelCode": "IND",
            "coverageLevel": "Individual",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "benefitAmount": "6000",
            "inPlanNetworkIndicatorCode": "N",
            "inPlanNetworkIndicator": "No",
            "additionalInformation": [
                {
                    "description": "INT MED AND RX"
                }
            ]
        },
        {
            "code": "G",
            "name": "Out of Pocket (Stop Loss)",
            "coverageLevelCode": "IND",
            "coverageLevel": "Individual",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "timeQualifierCode": "29",
            "timeQualifier": "Remaining",
            "benefitAmount": "6000",
            "inPlanNetworkIndicatorCode": "N",
            "inPlanNetworkIndicator": "No"
        },
        {
            "code": "G",
            "name": "Out of Pocket (Stop Loss)",
            "coverageLevelCode": "FAM",
            "coverageLevel": "Family",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "benefitAmount": "12000",
            "inPlanNetworkIndicatorCode": "N",
            "inPlanNetworkIndicator": "No",
            "additionalInformation": [
                {
                    "description": "INT MED AND RX"
                }
            ]
        },
        {
            "code": "G",
            "name": "Out of Pocket (Stop Loss)",
            "coverageLevelCode": "FAM",
            "coverageLevel": "Family",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "timeQualifierCode": "29",
            "timeQualifier": "Remaining",
            "benefitAmount": "12000",
            "inPlanNetworkIndicatorCode": "N",
            "inPlanNetworkIndicator": "No"
        },
        {
            "code": "F",
            "name": "Limitations",
            "coverageLevelCode": "ESP",
            "coverageLevel": "Employee and Spouse",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "additionalInformation": [
                {
                    "description": "Innovation Health Discount"
                }
            ]
        },
        {
            "code": "F",
            "name": "Limitations",
            "coverageLevelCode": "ESP",
            "coverageLevel": "Employee and Spouse",
            "serviceTypeCodes": [
                "30"
            ],
            "serviceTypes": [
                "Health Benefit Plan Coverage"
            ],
            "timeQualifierCode": "32",
            "timeQualifier": "Lifetime",
            "additionalInformation": [
                {
                    "description": "Unlimited Lifetime Benefits"
                }
            ]
        },
        {
            "code": "1",
            "name": "Active Coverage",
            "coverageLevelCode": "ESP",
            "coverageLevel": "Employee and Spouse",
            "serviceTypeCodes": [
                "80"
            ],
            "serviceTypes": [
                "Immunizations"
            ],
            "planCoverage": "Open POS Plus"
        },
        {
            "code": "A",
            "name": "Co-Insurance",
            "coverageLevelCode": "ESP",
            "coverageLevel": "Employee and Spouse",
            "serviceTypeCodes": [
                "80"
            ],
            "serviceTypes": [
                "Immunizations"
            ],
            "benefitPercent": "0",
            "inPlanNetworkIndicatorCode": "Y",
            "inPlanNetworkIndicator": "Yes",
            "additionalInformation": [
                {
                    "description": "All Other In-Network Providers"
                },
                {
                    "description": "Flu Vaccine in Office"
                },
                {
                    "description": "Flu Vaccine"
                },
                {
                    "description": "Adult Immunization in Office"
                },
                {
                    "description": "AGES 18-99"
                },
                {
                    "description": "Adult Immunization"
                },
                {
                    "description": "AGES 18-99"
                },
                {
                    "description": "Flu Vaccine by PCP in Office"
                },
                {
                    "description": "Flu Vaccine by PCP"
                }
            ]
        },
        {
            "code": "B",
            "name": "Co-Payment",
            "coverageLevelCode": "ESP",
            "coverageLevel": "Employee and Spouse",
            "serviceTypeCodes": [
                "80"
            ],
            "serviceTypes": [
                "Immunizations"
            ],
            "benefitAmount": "0",
            "inPlanNetworkIndicatorCode": "Y",
            "inPlanNetworkIndicator": "Yes",
            "additionalInformation": [
                {
                    "description": "All Other In-Network Providers"
                },
                {
                    "description": "Flu Vaccine in Office"
                },
                {
                    "description": "Flu Vaccine"
                },
                {
                    "description": "Adult Immunization in Office"
                },
                {
                    "description": "AGES 18-99"
                },
                {
                    "description": "Adult Immunization"
                },
                {
                    "description": "AGES 18-99"
                },
                {
                    "description": "Flu Vaccine by PCP in Office"
                },
                {
                    "description": "Flu Vaccine by PCP"
                }
            ]
        },
        {
            "code": "F",
            "name": "Limitations",
            "coverageLevelCode": "ESP",
            "coverageLevel": "Employee and Spouse",
            "serviceTypeCodes": [
                "80"
            ],
            "serviceTypes": [
                "Immunizations"
            ],
            "inPlanNetworkIndicatorCode": "Y",
            "inPlanNetworkIndicator": "Yes",
            "additionalInformation": [
                {
                    "description": "All Other In-Network Providers"
                },
                {
                    "description": "Flu Vaccine in Office/Plan Ded Waived"
                },
                {
                    "description": "Flu Vaccine/Plan Ded Waived"
                },
                {
                    "description": "Adult Immunization in Office/Plan Ded Waived"
                },
                {
                    "description": "Adult Immunization/Plan Ded Waived"
                },
                {
                    "description": "Flu Vaccine by PCP in Office/Plan Ded Waived"
                },
                {
                    "description": "Flu Vaccine by PCP/Plan Ded Waived"
                }
            ]
        },
        {
            "code": "A",
            "name": "Co-Insurance",
            "coverageLevelCode": "ESP",
            "coverageLevel": "Employee and Spouse",
            "serviceTypeCodes": [
                "80"
            ],
            "serviceTypes": [
                "Immunizations"
            ],
            "benefitPercent": ".3",
            "authOrCertIndicator": "Y",
            "inPlanNetworkIndicatorCode": "N",
            "inPlanNetworkIndicator": "No",
            "additionalInformation": [
                {
                    "description": "Flu Vaccine by Primary Care Physician in Office"
                },
                {
                    "description": "COINS APPLIES TO OUT OF POCKET"
                },
                {
                    "description": "AGES 22-99"
                },
                {
                    "description": "Flu Vaccine by Primary Care Physician"
                },
                {
                    "description": "COINS APPLIES TO OUT OF POCKET"
                },
                {
                    "description": "AGES 22-99"
                },
                {
                    "description": "Flu Vaccine by Primary Care Physician in Office"
                },
                {
                    "description": "COINS APPLIES TO OUT OF POCKET"
                },
                {
                    "description": "AGES 22-99"
                },
                {
                    "description": "Flu Vaccine"
                }
            ]
        },
        {
            "code": "B",
            "name": "Co-Payment",
            "coverageLevelCode": "ESP",
            "coverageLevel": "Employee and Spouse",
            "serviceTypeCodes": [
                "80"
            ],
            "serviceTypes": [
                "Immunizations"
            ],
            "benefitAmount": "0",
            "authOrCertIndicator": "Y",
            "inPlanNetworkIndicatorCode": "N",
            "inPlanNetworkIndicator": "No",
            "additionalInformation": [
                {
                    "description": "Flu Vaccine by Primary Care Physician in Office"
                },
                {
                    "description": "AGES 22-99"
                },
                {
                    "description": "Flu Vaccine by Primary Care Physician"
                },
                {
                    "description": "AGES 22-99"
                },
                {
                    "description": "Flu Vaccine by Primary Care Physician in Office"
                },
                {
                    "description": "AGES 22-99"
                },
                {
                    "description": "Flu Vaccine"
                },
                {
                    "description": "AGES 22-99"
                }
            ]
        },
        {
            "code": "F",
            "name": "Limitations",
            "coverageLevelCode": "ESP",
            "coverageLevel": "Employee and Spouse",
            "serviceTypeCodes": [
                "80"
            ],
            "serviceTypes": [
                "Immunizations"
            ],
            "inPlanNetworkIndicatorCode": "W",
            "inPlanNetworkIndicator": "Not Applicable",
            "additionalInformation": [
                {
                    "description": "Plan Requires PreCert"
                }
            ]
        },
        {
            "code": "F",
            "name": "Limitations",
            "coverageLevelCode": "ESP",
            "coverageLevel": "Employee and Spouse",
            "serviceTypeCodes": [
                "80"
            ],
            "serviceTypes": [
                "Immunizations"
            ],
            "additionalInformation": [
                {
                    "description": "Commerci"
                },
                {
                    "description": "Plan includes NAP"
                }
            ]
        }
    ]
}

How do Raw-X12 Eligibility requests and responses work?

We also support a traditional X12 EDI 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.

The Eligibility Raw-X12 endpoint is as follows:

https://apis.changehealthcare.com/medicalnetwork/eligibility/v3/raw-x12

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

An X12 EDI Eligibility request appears similar to the following:

POST /medicalnetwork/eligibility/v3/raw-x12 HTTP/1.1
Host: sandbox.apis.changehealthcare.com
Authorization: Bearer <Your-Access-Token>
Content-Type: application/json
{
    "x12": "ISA*00*          *01*password  *ZZ*something      *ZZ*EMDEON         *200708*0603*^*00501*123456789*0*P*:~GS*HS*LLX1210001*MTEXE*20200708*0603*123456789*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*0123456789~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*291*RD8*20100101-20100102~EQ*98~SE*21*123456789~GE*1*123456789~IEA*1*123456789~"
}

An X12 EDI 271 response appears similar to the following:

{
    "x12": "ISA*00*          *01*SomePwd   *ZZ*EMDEON         *ZZ*TPG00000       *201006*0641*^*00501*123456789*0*T*:~GS*HB*MTEXE*LLX1210001*20131015*2219*123456789*X*005010X279A1~ST*271*946380841*005010X279A1~BHT*0022*11*123456789*20200708*0603~HL*1**20*1~NM1*PR*2*Unknown*****PI*serviceId~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~"
}

Understanding API Features

Using Mandatory Fields and Predefined Values

Each trading partner has differing requirements for expected data in eligibility and benefits requests. This section aims to provide some best practices across our entire network, while aiming to give you the tools to craft partner-specific requests where necessary.

Fields in the requests object

controlNumber - required - this is a 9-digit number required by the X12 specifications for eligibility transactions; you create this number that is unique to a transaction at the daily level or longer to assist with troubleshooting transactions

tradingPartnerServiceId - required - this lets us know which trading partner (payer) we route the transaction to. Values are obtained from the payer list.

Fields in the provider object

npi - some form of identifier is required with each Eligibility transaction you submit; NPI is the most widely recognized identifier and will give you the best results; taxId is also valid but not universally accepted by trading partners.

organizationName - while not necessarily required, you use this field to identify the entity submitting the transaction; providers submitting directly will use firstName and lastName instead of this field.

Fields in the subscriber and dependents objects

A search option is a set of fields that will yield a successful response from a payer if there's a member match. Trading partners typically require specific fields in combination to ensure retrieval of requested records.

Search options will allow you to, in some cases, get a successful response even without a piece of information like the subscriber ID. A common, name-based search option would include the firstName,lastName, and dateOfBirth of the member in question.

If you always have the subscriber ID, then we suggest sending a request containing the memberId, firstName, lastName, and dateOfBirth fields.

Fields in the encounter object

beginningDateOfService - will default to the date of the request if not provided. Please refer to a payer's EDI guide to see if requests for past dates of service are allowed.

serviceTypeCodes - will default to 30 if not provided, which provides the broadest overview of a patient's health plan and benefit details. Customers requesting more specialized benefits information can adjust the service type code here.

Eligibility API enrollment requirements

Several payers require NPI enrollment before they will send successful eligibility responses. For the list of payers who require enrollment, please refer to the payer list on ConnectCenter. For more information, your Change Healthcare implementation analyst will be able to help.

What are some typical Errors and Error codes?

Here is an example error for a request submitted with a mistake in the control number:

{
    "errors": [
        {
            "field": "controlNumber",
            "description": "BAD_CONTROL_NUMBER"
        }
    ]
}

Here is an example of a AAA error:

{
 "responses": [
 {
   "controlNumber": "000000001",
   "tradingPartnerId": "TPG00000111",
   "errors": [
    {
      "errorCode": "42",
      "errorDescription": "Unable to Respond at Current Time",
      "errorLocation": "Loop 2000A"
    }
   ]
  }
  ]
}

You can download a full list of AAA errors from the Attachments tab.

Additional error types

AAA emulates errors in the Sandbox that you will see in production when an API does not find a subscriber. You can download a full list of AAA errors from the Attachments tab.

{
    "errors": [
        {
            "field": "subscriber",
            "description": "Please use predefined canned users for non-prod environments: firstName was not predefined."
        },
        {
            "field": "AAA",
            "description": "Transaction contained a AAA rejection"
        },
        {
            "field": "73",
            "description": "Invalid/Missing Subscriber/Insured Name",
            "followupAction": "Please Correct and Resubmit",
            "location": "Loop 2100C"
        },
        {
            "field": "71",
            "description": "Patient Birth Date Does Not Match That for the Patient on the Database",
            "followupAction": "Please Correct and Resubmit",
            "location": "Loop 2100C"
        }
    ]
}

Change Log

API Name API Version Date Introduced Available Until
Eligibility v3 4-17-19
Eligibility v2 1-1-19 Deprecated
Eligibility v1 1-1-18 Deprecated

Release Notes:

v3

  • Security and Authorization changes in v3
  • host and url changes
  • Remove the Accept application/vnd.changehealthcare.medicaleligibility-v2+json header mentioned in v2, no need to send or increment, Versioning will be managed via the url path.

v2

  • request/response is now a single medical eligibility request/response
  • error response schema changed
  • adding address to subscriber and dependents in response
  • must send Header: Accept application/vnd.changehealthcare.medicaleligibility-v2+json

v1

  • Initial offering of Eligibility