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/parserpackage.
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:
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 ofinterpret271for the response.errors: each error that the payer reported, in the same order aseligibility.requestErrors. When the companion guide lists an error, its entry includes the HETSconditionanddescription.findings: the problems that the profile found in the response.members: oneMedicareViewobject for each member, in the same order aseligibility.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: the2100ANM1segment doesn't haveNM101set toPR,NM108set toPI, andNM109set toCMS.unexpected-receiver: the2100BNM101element isn't1P,80, orFA.member-id-placeholder: the member'sNM109element isMISSING. HETS sends this value withAAA03set to72when the request had no Medicare Beneficiary Identifier (MBI). ThememberIdfield still containsMISSING.unlisted-error: the level andAAA03code of anAAAsegment 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:
| Field | Rows |
|---|---|
partA, partB | Coverage rows with EB04 set to MA or MB. |
partACostShares, partBCostShares | Cost share rows with EB04 set to MA or MB. |
qmb | Cost share and other party rows with EB04 set to QM. |
medicareAdvantage | Other party rows with EB01 set to U and EB03 set to 30. |
partD | Other party rows with EB01 set to R and EB03 set to 88. |
msp | Other 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: theREFsegment with qualifier18.plan: theREFsegment with qualifierN6.planName: theREF03element of theREFsegment with qualifierN6.
MSP entries include the following fields:
policyNumber: theREFsegment with qualifierIG.ref6P: theREFsegment with qualifier6P, 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, and21244.- An
EBrow withEB01set toDand anMSGsegment that containsSubscriber address -followed by the address as SSA sent it.
In that case, interpretRoute does the following:
- Adds a
placeholder-addressfinding on theN3segment. - Puts the address from the
MSGsegment inssaAddress. When HETS sendsUnknownor noMSGsegment,ssaAddressisundefined.
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