API & Services Connection™
Request Sandbox AccessMarketplaceApp RegistryCommunityQuick Reference

Response Body Contents

Suggest Edits

Identification and Policy Confirmation

This topic describes the Eligibility response by each JSON object it contains. You can send as little or as much provider and subscriber information as needed to get a successful result. Check Using “Bare Minimum” Eligibility requests if you want to simplify sending Eligibility requests for routine submission work.

The Eligibility response leads off with information from the transaction set header (controlNumber) and identifies the service provider that is submitting the Eligibility request.

JSON Eligibility ObjectDescription
json { "controlNumber": "000000001", "reassociationKey": "000000001", "tradingPartnerServiceId": "UHC", "submitterTransactionIdentifier": "7894445309" "provider": { "providerName": "happy_doctors_group", "entityIdentifier": "Provider", "entityType": "Non-Person Entity", "npi": "0123456789" },
  • The header attributes (controlNumber, `reassociationKey, tradingPartnerServiceId, and submitterTransactionIdentifier) derive from the ISA/IEA envelope and the BHT segment for the transaction. These elements do not have a loop and are required for all Eligibility API transactions.

    • Optum (formerly, Change Healthcare) Support can use the submitterTransactionIdentifier for troubleshooting purposes.

  • The provider object describes the submitting provider's information.

  • The entityIdentifier attribute describes the information receiver that sent the Eligibility request, in this case, a Provider.
    • They will typically be receiving the patient's insurance information as the response to their request.
  • The entityType will always be either a Person or a Non-Person entity. In this example, the submitting provider's NPI follows.

    • 📝 The provider object and its accompanying information describe the information receiver in the EDI standard documentation.

    Subscriber object

    Contains the standard identification information and the subscriber's demographic information.
    JSON Eligibility ObjectDescription
    json }, "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": "000000001", "originatingCompanyIdentifier": "9EMDEON999" } ],
  • The subscriber object is required when the subscriber is the patient.
  • The subscriberTraceNumbers link the 271 response to the 270 request.
    • It is an optional request feature and if used, requires its corresponding use in the 271 response. The trace numbers are used when the 270 request is processed in real time, which is the vast majority of Medical Network API transactions.

    Payer object — Identifying the Payer

    The Payer object describes the insurance payer (and information source) for the policy. It also describes the payer type that underwrites the policy.

    JSON Eligibility ObjectDescription
    json "payer": { "entityIdentifier": "Payer", "entityType": "Non-Person Entity", "name": "Unknown", "payorIdentification": "9496" }, "planInformation": { "socialSecurityNumber": "111111111" }, "planDateInformation": { "plan": "20150219-20160818" }, The Payer will typically be a Non-Person entity. If the entityType is a Non-Person entity, the object containing these values does not need the first name. It requires only the Last Name/Organization Name, which the API reports as name for the corporate name of the payer. The API also inserts the payer's payorIdentification as the last field. This element contains the Payer ID value that uniquely denotes each individual payer in the United States healthcare system.

    The planDateInformation object describes the insurance coverage dates. It consists of two dates: first, the Plan Begin Date (or the date from the preceding 18 months since the plan took effect, whichever is more recent); the second is the eligibility submission date. You can find out more about this requirement on Page 20 of the ASC X12 Consolidated 270-271 Guide.
    📝 The payer object and its accompanying information describe the information source in the 270/271 standard documentation.

    PlanStatus object

    After the content describing the subscriber, provider, and payer, the planStatus object describes the core status information for the subscriber’s insurance coverage:

    JSON Eligibility ObjectDescription
    json "planStatus": [ { "statusCode": "1", "status": "Active Coverage", "planDetails": "QMB", "serviceTypeCodes": [ "30" "88" "BV" "BU" "BT" ... ] } ],
  • planStatus describes the key details of the patient's insurance coverage. QMB denotes a Qualified Medicare Beneficiary. The main element in Plan Status is a list of codes, called serviceTypeCode (serviceTypeCodes). Each code is associated with a medical specialty or service. Under Plan Status, the serviceTypeCode list shows the medical services that are covered by the patient's insurance.

  • benefitsInformation object (see below) separately provides the details of each medical service's coverage.

    • 📝 Many Eligibility responses simply confirm an active insurance policy by sending the only listed "serviceTypeCode 30". Any other listed serviceTypeCode is optional for the payer response. The submitter can request more details about other covered benefits.

    BenefitsInformation object — Navigating Insurance Codes

    BenefitsInformation comprises a key part of the Eligibility response. It describes the covered medical benefits, in further detail, to which the patient is entitled. It also includes information about who may be responsible for paying some medical costs, including patient responsibility, and any second or third payers who may be involved. All of this information will be shown for either the subscriber or a dependent of the subscriber. For deeper information on how benefits information is structured, including looping elements, see Page 295 of the ASC X12 Consolidated 270-271 Guide.

    JSON Eligibility ObjectDescription
    json { "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-20171130" } }, { "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-20171130" } { "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" } } }, You will often see multiple segments under benefitsInformation. Each segment represents a medical coverage benefit.
    Example: a chiropractic visit will have a different benefit structure from a Primary Care visit. Each has its benefits structure and distinct segment in the Eligibility response body. The information receivers decides if they want individual benefits shown in the response.

    The first two values in each segment, code and name, identify the top-level benefit information. When you see codes A, B, C, G, J, or Y, the current object is describing a patient responsibility (coinsurance, co-payment, deductible and so on).
  • coverageLevelCode is IND for Individual. For readability, the API's JSON response provides the coverageLevel descriptive value for this code (individual). It shows who is covered by the policy; the entire family (FAM), Employee Only (EMP), or other options.
  • serviceTypeCodes may list and describe up to 99 individual service benefits for a single inquiry. If the response only gives a confirmation of general coverage benefits (using serviceTypeCode 30), an example similar to this one will be shown. Here, a patient's Medicare coverage describes the top-level Medicare payer, with Medicare Part A and Part B as other or additional payers for the subscriber.
  • insuranceTypeCode is also a code pair with insuranceType in our API. Our API describes the code (such as MA, for Medicare Part A) as a second attribute. It describes the product type of the insurance, such as Medicare Part A/Part B, Long-Term Care, Auto Insurance Policy, and many others.
  • ServiceTypes also appear in this block of information, showing how benefits coverage applies to each medical service. In this example, the phrase Health Benefit Plan Coverage corresponds to serviceTypeCode 30.
    • json "benefitsDateInformation": { "plan": "20160818-20160818" }
  • benefitsDateInformation describes the insurance coverage dates. Its data consists of two dates: 1) the Plan Begin Date (or the date from the preceding 18 months from the current submission date, whichever is more recent); 2) the eligibility submission date.
  • `benefitsDateInformation` describes the insurance coverage dates. Its data consists of two dates: 1) the Plan Begin Date (or the date from the preceding 18 months from the current submission date, whichever is more recent); 2) the eligibility submission date.

    • serviceTypeCode 30 is a common value in Eligibility queries. It identifies in-effect coverage for the broad array of typical medical services covered by the plan. In this case, Medicare is the classic broad-coverage payer in the United States. It provides coverage for a large collection of medical services. Payers will often confirm medical insurance coverage by sending a response listing only the 30 value in the benefitsInformation loop.

    Insurers/payers can also give more granular information about benefits coverage.

    A quick Insurance Type Codes search in the X12 Eligibility Consolidated 270/271 Guide gives the complete serviceTypeCode list, spanning several pages. To use this document, you must have an active X12 subscription.

    Benefits, Time Periods, and Coverage Amounts

    Every serviceType segment has more or less the same format:

    JSON Eligibility ObjectDescription
    json "serviceTypes": , "insuranceTypeCode": "MA", "insuranceType": "Medicare Part A", "timeQualifierCode": "7", "timeQualifier": "Day", "benefitAmount": "164.5", "benefitsDateInformation": { "admission": "20170101-20171231" } Note the repetition of insuranceTypeCode, here, it is called out to identify the insurance coverage for each individual service. This value can differ from the umbrella insuranceTypeCode value; in this case, the umbrella insurance code is QM for a qualified Medicare beneficiary, and the service's insuranceTypeCode is MA for Medicare Part A.

  • timeQualifierCode shows the benefit billing period, which is Daily, using 7 as the EDI value (this value does NOT define a weekly time span). Our API provides the timeQualifier description, day, so benefit coverage is tracked daily.

  • benefitAmount is added based on the timeQualifier, so the daily benefit amount of the Skilled Nursing Care service is $164.50.

    • Updated 3 months ago