Skip to content

parser / guides / 02

Read CMS HETS responses

This page describes how to read a 271 eligibility response from CMS HETS by using interpretRoute with hetsProfile. HETS is the system that answers Medicare eligibility requests. The profile applies the 271 rules from the CMS HETS 270/271 Companion Guide, version 15-1 (May 2026). It does the following:

  • Checks the response against the rules in the companion guide.
  • Gives each error that the companion guide lists its HETS meaning.
  • Sorts each member's benefit rows into Medicare lists.

Before you begin ​

Make sure that you have the following:

  • A 271 response to a 270 request that you sent to HETS.
  • The @ediocracy/parser package.

To have the library pick the profile from the 2100A payer ID in the response, use interpretRoute(entry) instead of passing hetsProfile. For more information, see Apply the payer's rules.

Read a response ​

The following example reads a file of 271 responses and prints the Medicare results for each member:

ts
import { readFile } from 'node:fs/promises';

import { readX12 } from '@ediocracy/parser';
import { read271s } from '@ediocracy/parser/271';
import { hetsProfile, interpretRoute } from '@ediocracy/parser/271/routes';

const text = await readFile('response.x12', 'utf8');

for (const entry of read271s(readX12(text))) {
    const result = interpretRoute(entry, hetsProfile);

    for (const finding of result.findings) {
        console.log('Finding:', finding.code, finding.message);
    }

    for (const error of result.errors) {
        console.log('Error:', error.condition ?? error.rejectReason, error.description);
    }

    for (const view of result.members) {
        const advantageContracts = view.medicareAdvantage.map(plan => plan.contract);
        const partDContracts = view.partD.map(plan => plan.contract);

        console.log('Part A rows:', view.partA.length, 'Part B rows:', view.partB.length);
        console.log('Medicare Advantage:', advantageContracts, 'Part D:', partDContracts);

        if (view.ssaAddress) {
            console.log('SSA address:', view.ssaAddress);
        }
    }
}

For each item that read271s returns, interpretRoute(entry, profile) returns a RouteEligibility object. The object has the following fields:

  • eligibility: the unchanged result of interpret271 for the response.
  • errors: each error that the payer reported, in the same order as eligibility.requestErrors. When the companion guide lists an error, its entry includes the HETS condition and description.
  • findings: the problems that the profile found in the response.
  • members: one MedicareView object for each member, in the same order as eligibility.members.

Findings ​

The findings field uses codes from RouteFindingCode and HetsFindingCode. The profile reports the following codes:

  • unexpected-delimiters: the ISA declares separators other than *, |, ~, and ^. HETS always uses these separators.
  • unexpected-source: the 2100A NM1 segment doesn't have NM101 set to PR, NM108 set to PI, and NM109 set to CMS.
  • unexpected-receiver: the 2100B NM101 element isn't 1P, 80, or FA.
  • member-id-placeholder: the member's NM109 element is MISSING. HETS sends this value with AAA03 set to 72 when the request had no Medicare Beneficiary Identifier (MBI). The memberId field still contains MISSING.
  • unlisted-error: the level and AAA03 code of an AAA segment aren't in the HETS error table.
  • placeholder-address: HETS couldn't format the beneficiary's address. For more information, see Placeholder address.

Errors ​

When HETS lists an AAA03 code for the level of the AAA segment, the entry in errors has a condition key and a one-line description. For example, AAA03 set to 72 at the subscriber level has the condition mbi-not-matched. For an error that HETS doesn't list, condition and description are undefined.

Medicare views ​

Each MedicareView object contains lists of rows from eligibility. Each list keeps its rows in the order that they appear in the response, including rows that repeat other rows. A row can be in more than one list.

The following table shows the rows in each list:

FieldRows
partA, partBCoverage rows with EB04 set to MA or MB.
partACostShares, partBCostSharesCost share rows with EB04 set to MA or MB.
qmbCost share and other party rows with EB04 set to QM.
medicareAdvantageOther party rows with EB01 set to U and EB03 set to 30.
partDOther party rows with EB01 set to R and EB03 set to 88.
mspOther party rows with EB01 set to R, EB03 set to 30, and a Medicare Secondary Payer (MSP) insurance type in EB04.

Medicare Advantage and Part D entries include the following fields:

  • contract: the REF segment with qualifier 18.
  • plan: the REF segment with qualifier N6.
  • planName: the REF03 element of the REF segment with qualifier N6.

MSP entries include the following fields:

  • policyNumber: the REF segment with qualifier IG.
  • ref6P: the REF segment with qualifier 6P, as HETS sent it. HETS uses this segment for a group number, a date of loss, or a missing group number, so the library doesn't interpret the value.

Qualified Medicare Beneficiary (QMB) rows are only in qmb, even when EB05 says Medicare Part A or Medicare Part B.

Placeholder address ​

When HETS can't format the address that the Social Security Administration (SSA) has for the beneficiary, it sends the following placeholder values:

  • N301: Refer to MSG for Subscriber address.
  • N4: Baltimore, MD, and 21244.
  • An EB row with EB01 set to D and an MSG segment that contains Subscriber address - followed by the address as SSA sent it.

In that case, interpretRoute does the following:

  • Adds a placeholder-address finding on the N3 segment.
  • Puts the address from the MSG segment in ssaAddress. When HETS sends Unknown or no MSG segment, ssaAddress is undefined.

The member's details.address in eligibility still contains the Baltimore values.

Limitations ​

The MedicareView object doesn't include the following rows. To get them, read eligibility.

  • Hospital and skilled nursing facility (SNF) spells
  • Home health
  • Hospice
  • End-stage renal disease (ESRD)
  • Preventive services
  • Therapy and rehabilitation
  • Medicare Diabetes Prevention Program (MDPP)
  • Vaccinations
  • Prior authorization