Contents of the Eligibility Request Body

Understanding the JSON code for the Eligibility Request

The Eligibility request body consists of a set of JSON objects that contain the key parameters to verify a patient’s medical coverage. These blocks of information define the contents of your Eligibility query to the Change Healthcare clearinghouse.

NOTE: JSON attributes in our APIs use snake-case, with the first letter of the attribute in lower case as in `tradingPartnerServiceId`. Our APIs are case-sensitive and your JSON request bodies must observe this convention.
JSON Eligibility Object Description
POST ${api_basepath} HTTP/1.1
Host: ${apigee_host}
Authorization: Bearer <Your-Access-Token>
Content-Type: application/json
  "tradingPartnerServiceId": "UHC",

The JSON attributes that comprise the leading elements of the request body:

  • ControlNumber – a single arbitrary value that the requestor defines in the initial Eligibility API transaction request, perhaps by a random number generator. All parties to the Eligibility transaction refer to this number to ensure accurate responses and completion of the exchange.

Control Numbers must be defined as a nine-digit unsigned numeric value.

  • TradingPartnerServiceId – the Payer ID. You can use the payer’s ConnectCenter Realtime Payer ID value as the tradingPartnerServiceId.

  • ProviderType – the Partner type requested to verify eligibility. This field is optional.

The Provider Object


JSON Eligibility Object Description
    "Provider": {
        "organizationName": "provider_name",
        "npi": "0123456789",
        "serviceProviderNumber": "54321",
        "providerCode": "AD",
        "referenceIdentification": "54321g"

The Provider object describes the medical service provider submitting the eligibility request:

  • OrganizationName – the business name of the provider. Required value to identify the entity submitting the transaction; providers submitting directly can use firstName and lastName instead of this field.

  • Npi – the National Provider ID number for the submitting provider. Some form of identification for the provider is required for any eligibility transaction; npi is the most common.

Optional values for the provider object:

  • ServiceProviderNumber – the Service Provider ID number.

  • ProviderCode – the clearinghouse-assigned Provider Code. This two-digit code identifies the medical provider type, such as Admitting (AD), Billing (BI), and others. To see the complete code list, use the PDF search term 'Provider Code' in the X12 270/271 Implementation Guide.

  • ReferenceIdentification – the Healthcare Provider Taxonomy code value.

The Subscriber Object


JSON Eligibility Object Description
    "subscriber": {
        "memberId": "0000000000",
        "firstName": "johnOne",
        "lastName": "doeOne",
        "gender": "M",
        "dateOfBirth": "18800102",
        "ssn": "000000000",
        "idCard": "card123"

The Subscriber JSON object is the medical insurance subscriber. The object contains several identity and demographic data fields identifying the insurance policyholder, including memberId, firstName, lastName, dateOfBirth, gender, ssn and idCard, which is the subscriber’s insurance plan card number.

The Dependents Object


JSON Eligibility Object Description
    "dependents": [
            "groupNumber": "0000000000"

Dependents is an array of one or more records describing one or more dependents of the subscriber who are on the insurance policy.

The encounter for the eligibility request may involve the subscriber or a dependent. If a dependent is not involved in the encounter, you can omit dependent information from the request. This content is Situational for that reason.

The dependent object is subordinate to the subscriber. In some cases, the person listed as a Dependent for insurance purposes may need to be listed as the Subscriber.

The Encounter Object


JSON Eligibility Object Description
    "encounter": {
      "beginningDateOfService": "20100101",
      "endDateOfService": "20100102",
      "serviceTypeCodes": [

The Encounter object describes the beginning and end dates of the medical services associated with the eligibility request. It also contains the situational serviceTypeCodes field.

The object itself is required in your request, but you have choices to define it based on whether the medical encounter is a single occasion on a single date, or if it spans a longer period of time.

  • DateOfService - The date of provider service to the subscriber. The singular value is required if the encounter spans only a single visit on a single day. Otherwise, use beginningDateOfService and endDateOfService to delineate the time span for the medical services.

  • ServiceTypeCodes – (Situational) Request eligibility for service types using the optional serviceTypeCodes object. If you don’t specify a service type, you make the request for general benefit coverage information. Some trading partners may not support service type inquiries.

  • ProcedureId – (Situational) You can specify procedureId values from a standard list of IDs that the proposed procedure is associated with. The most common is the Healthcare Common Procedure Coding System (HCPCS), which defines reference codes for items and services provided in the delivery of health care. Providers will likely have a smaller set of well-understood procedure IDs associated with their practice.

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.