cyclone/docs/reference/x12naming.md

X12 naming conventions

A short glossary of the names and indices used throughout Cyclone's parsers.

Segments

Two- or three-letter codes that identify a row type. The codes are mnemonic: CLM = claim, NM1 = name, BPR = beginning segment for payment order/remittance advice, SVC = service, DTM/DTP = date/time/period.

Elements

Inside a segment, elements are separated by * and are 1-indexed. So CLM01 is the first element of the CLM segment — the patient control number on 837P. CLM02 is the second element — the total claim charge.

Composite elements

A single element can carry sub-fields, separated by :. The sub-fields are also 1-indexed, suffixed to the element index:

• CLM05-1 = place of service (Facility Type Code)
• CLM05-2 = facility code qualifier
• CLM05-3 = claim frequency code

In the Python code, this is claim.place_of_service, claim.facility_code_qualifier, and claim.frequency_code on the ClaimHeader model in cyclone/parsers/models.py.

Loops

Four-digit numeric IDs, hierarchical:

• 2000A (Billing Provider hierarchy) contains
  • 2000B (Subscriber hierarchy) which contains
    • 2300 (Claim) which contains
      • 2400 (Service line)

In cyclone.parsers, the parse_837 walker descends through these loops explicitly.

Common qualifiers Cyclone cares about

Qualifier	Meaning	Where
ABK	ICD-10 principal diagnosis	HI01-1
ABF	ICD-10 diagnosis	HI01-1
B	Facility code qualifier (CMS POS)	CLM05-2
MC	Medicaid (claim filing indicator)	835 CLP06
PR	Payer	835 N1*PR
PE	Payee	835 N1*PE
G1	Prior authorization	837P REF01
TJ	Federal taxpayer ID	837P REF01 (rendering provider TIN)
1	Original claim	837P CLM05-3
7	Replacement claim	837P CLM05-3
8	Void/cancel claim	837P CLM05-3

The four delimiters

All four are declared in the ISA segment (positions 103–106 in the ISA fixed-width header) and reused throughout the file. Cyclone's tokenizer in cyclone/parsers/segments.py reads the ISA first, then splits the rest of the file by those characters.

• * — element separator
• : — component (sub-element) separator
• ~ — segment terminator
• ^ — repetition separator