Eligibility v3

Summary API Attachments FAQ CHANGE LOG    
awss
 

Overview

The Eligibility API takes the standard established in the X12 EDI 270/271 transaction and translates this standard to JSON so that it is more accessible to developers and easily integrated into users’ applications. We manage X12 standards behind the scenes and give you access to copays, coinsurances, deductibles, and more in an easy-to-use, human-readable format.

Our Eligibility API solution provides patient profile and benefits insights to help support appropriate care delivery, as well as efficient and accurate reimbursement. For providers, this means better front-end information to improve claiming processes and reimbursement rates. For payers, it means less time spent pending, rejecting, and reworking claims

API Onboarding

See the Security and Authorization section in this portal to learn more about using our APIs. Most of our APIs are private and require credentials to gain access.

After receiving your client_id and client_secret for our sandbox environment, you can test the API from within our interactive documentation, using an application such as Postman, or from your own stack.

Try our Postman Collection Run in Postman

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

We sure do. After receiving your client_id and client_secret for our sandbox environment, you can test the API from within our interactive documentation, using an application such as Postman, or from your own stack.

We have a list of test service IDs to use in sandbox for a variety of different responses. Please see the Eligibility Sandbox Test Responses document located in the Attachments tab.

Try our Postman Collection Run in Postman

What information needs to go in the request header?

In the header for an Eligibility API request, you need to pass 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"
}'

This is a precursor to making an Eligibility API call, which might have the following headers:

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

Read all about our protocols in the Security -> Authorization section of this portal.

When you're ready for production, simply remove sandbox from the URL.

What does a typical API call 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?

{
    "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"
                }
            ]
        }
    ]
}

Mandatory fields

Each trading partner varies when it comes to required fields for 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.

Sample request body

{
  "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"
    ]
  }
}

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

tradingPartnerId - required - this lets us know which trading partner (payer) we will be routing the transaction to

Note: you can also use tradingPartnerServiceId to route the transaction; for a full overview of how we handle tradingPartnerId and tradingPartnerServiceId, please visit our See Medical Network - > Trading Partners

Fields in the provider object

npi - some form of identifier is required with each 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, we recommend using 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

Our Trading Partner API provides you with the different member search options available for a specific trading partner. A search option is a set of fields that will yield a successful response from a payer if there's a member match.

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 using memberId, firstName, lastName, and dateOfBirth.

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

There are several payers who require NPI enrollment before they will send successful eligibility responses. For the list of payers who require enrollment, please refer to the payer list. For more information, your implementation analyst will be able to help.

Error codes

Example system error:

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

Example AAA error:

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

Sandbox predefined fields and values

The following fields must have one of the canned values provided.

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"


The field can appear at any level of the request model, it most have the canned value to have a successful response


If you don't use the provided canned values, you will get errors like the following:

{
    "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"
        }
    ]
}

AAA emulate the error you will see in prod when a subscriber is not found. A full list of AAA errors can be downloaded from the Attachments tab.

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