The parser reads a 271 transaction set into a Response271 object. The object contains the payers that answered, the providers that asked, the subscribers and their dependents, and the benefits for each person.
The following example reads the first transaction set in a file and prints its payers, providers, and benefits:
import { readFile } from 'node:fs/promises';
import { readX12 } from '@ediocracy/parser';
import { read271 } from '@ediocracy/parser/271';
const text = await readFile('response.x12', 'utf8');
const document = readX12(text);
const transaction = document.interchanges[0]?.groups[0]?.transactions[0];
if (transaction) {
const response = read271(transaction);
for (const source of response.sources) {
console.log('Payer:', source.name?.element(3), source.id);
}
for (const receiver of response.receivers) {
console.log('Provider:', receiver.name?.element(3), receiver.id);
}
for (const subscriber of response.subscribers) {
for (const benefit of subscriber.benefits) {
console.log(benefit.status, benefit.serviceTypes, benefit.planDescription);
}
}
}Read functions
The parser has two functions that read 271 transaction sets:
read271(transaction)reads one transaction set. It doesn't check that the transaction set is a 271. Use it when you have already picked the transaction set.read271s(document)reads every transaction set whoseST01is271, in the order that they appear. Each result includes theinterchangeandgroupthat contain the transaction set, so you can read the sender, receiver, and control numbers from their header segments. It also adds anunexpected-versionfinding whenGS08isn't005010X279A1.
Response fields
Response271 has the following fields:
sources: the payers that answered (the2100Aloop).receivers: the providers that asked (the2100Bloop).subscribers: the subscribers (the2000Cloop). Each subscriber has adependentsfield (the2000Dloop).reference: the reference identification fromBHT03.findings: the problems that the parser found while it read the response.
Parties and people
A Party has the following fields:
name: theNM1segment.idandidQualifier:NM109andNM108.errors: the errors that the payer reported for the party inAAAsegments.
A Person is a party that also has benefits, dependents, and traces (TRN segments).
Benefits
Each Benefit is one EB segment and the segments that qualify it. The parser returns codes as they appear in the response, without translation. For example, status is EB01, and serviceTypes is the list of EB03 repetitions. The eb field contains the EB segment itself, so you can read elements that the type doesn't name.
Apply the payer's rules
Some payers publish companion guides with rules for their 271 responses. The library has route profiles for five of these payers: CMS HETS, UnitedHealthcare, Humana, Cigna, and Health Care Service Corporation (HCSC).
To apply the right profile, call interpretRoute(entry) with an item that read271s returns. The function reads NM109 of the first 2100A loop that has an NM1 segment, and then applies the profile that lists that payer ID. The following table shows the payer IDs for each route:
route | Profile | Payer IDs (NM109) |
|---|---|---|
hets | hetsProfile | CMS |
uhc | uhcProfile | 87726, 52133, 00773, 94265 |
humana | humanaProfile | 61101, 61115, 65065, CX021 |
cigna | cignaProfile | 13 IDs. For the list, see Payer checks. |
hcsc | hcscProfile | Nine IDs. For the list, see Payer checks. |
The function returns a DetectedRoute object:
- When a profile lists the payer ID,
routenames the route, andresultcontains the profile's result. - When no profile lists the payer ID,
routeisundefined, andeligibilitycontains the result ofinterpret271.
UnitedHealthcare responses with other payer IDs also return route set to undefined, because the UnitedHealthcare companion guide applies only to the four payer IDs in the table.
The following example prints a different field for each route:
import { readFile } from 'node:fs/promises';
import { readX12 } from '@ediocracy/parser';
import { read271s } from '@ediocracy/parser/271';
import { interpretRoute } from '@ediocracy/parser/271/routes';
const text = await readFile('response.x12', 'utf8');
for (const entry of read271s(readX12(text))) {
const detected = interpretRoute(entry);
switch (detected.route) {
case 'hets': {
console.log('HETS Part A rows:', detected.result.members[0]?.partA.length);
break;
}
case 'cigna': {
console.log('Cigna:', detected.result.members.map(view => view.participation));
break;
}
case 'hcsc': {
console.log('HCSC groups:', detected.result.members.map(view => view.group?.number));
break;
}
case 'humana': {
console.log('Humana:', detected.result.members.map(view => view.lineOfBusiness));
break;
}
case 'uhc': {
console.log('UHC other payers:', detected.result.members.map(view => view.otherPayers.length));
break;
}
case undefined: {
console.log('No route. Members:', detected.eligibility.members.length);
break;
}
}
}