Understand the JSON-to-EDI Mapping

How the JSON-to-EDI API Mapping Works

Identify the Data Elements

Each piece of information in the JSON (e.g., patient name, provider NPI, service code, dates) maps to a specific segment and element in the EDI 278.

• If the segment is not included, none of its fields matter—even if they’re labeled “Required.”
• If the segment is included, all fields marked “Required” inside that segment must be present.
  • If you say “Type of contact: Phone”, you must also give the phone number.
  • If you say “Type of contact: Email”, you must also give the email address.
  • Qualifier and value always come as a pair.

Understand the EDI Structure

The 278 is organized into loops (hierarchical levels), segments (lines), and elements (fields). Example:

• Loop 2000A: UMO (Utilization Management Organization)
• Loop 2000B: Requester (Provider)
• Loop 2000C/D: Subscriber/Dependent (Patient)
• Loop 2000E: Patient Event (Service/Referral/Admission)
• Loop 2000F: Service (Procedure/Service Line)

Example of how a request is translated from JSON-to-EDI

Imagine you are a primary care doctor referring a patient to a specialist. You fill out a digital form with:

• Patient’s name and ID
• Reason for referral (e.g., chest pain)
• Preferred specialist and date
• Your own provider ID

This form is like a JSON request—structured, readable, and easy to fill out.

{
  "patient": {
    "firstName": "Joe",
    "lastName": "Doe",
    "dob": "1980-01-01",
    "memberId": "H1111111"
  },
  "provider": {
    "name": "North Memorial Health",
    "npi": "1851344907"
  },
  "service": {
    "type": "Consultation",
    "date": "2025-10-15",
    "diagnosisCode": "C34.32"
  }
}

ISA*00* *00* *ZZ*943207296 *ZZ*000000000000001*251009*1021*^*00501*916040697*0*P*:~
GS*HI*943207296*INQHEALTHHELP*20251009*102137*3294199*X*005010X215~
ST*278*0001*005010X215~
BHT*0007*28*1402448037*20251009*102137~
HL*1**20*1~
NM1*PR*2*Humana*****PI*HUMANA~
HL*2*1*21*1~
NM1*1P*2*North Memorial Health*****XX*1851344907~
HL*3*2*22*1~
NM1*IL*1*DOE*JOE****MI*H1111111~
DMG*D8*19800101~
HL*4*3*EV*0~
UM*HS*I*1*11:B~
DTP*AAH*D8*20251015~
HI*ABK:C34.32~
SE*21*0001~
GE*1*3294199~
IEA*1*916040697~

• The JSON is like a friendly conversation: “This is Joe Doe, born in 1980, needs a consultation for lung cancer.”
• The EDI is like a coded message: “NM1IL1DOEJOE…~” where each segment and code has a specific meaning.
• The API translates the JSON into X12 to ensure the payer receives their preferred format.

The Important EDI Background section at the end of this page provides additional details about the JSON-to-EDI conversion.

Understand the NM1 segment

The NM1 segment in EDI (X12) transactions is used to identify a person or organization. It includes multiple elements, but two of the most important for identification are:

• NM108 and NM109 are dependent on each other.
• Rule: If one is present, the other must also be present (EDI syntax rule P0809).
• NM108 gives context to NM109. Without NM108, the system would not know how to interpret the value in NM109.

Important EDI Background

NM1*1P*1*SMITH*JOHN****XX*1234567890~

• NM108 (what kind of ID is being used) = XX (this tells the system that the ID is an NPI).
• NM109 (the actual ID value) = 1234567890 (this is the actual NPI number of Dr. A.

Terminologies with examples

Example of mapping the JSON fields to EDI segments with R/S usage indicators:

• Required (R) segments must always be included in the EDI transaction; typically uses UM01 = Service Certification (SC) and may include additional segments like HCR for review decisions.
  • If the segment is not included, none of its fields matter—even if they are labeled “Required.”
    If the segment is included, all fields marked “Required” inside that segment must be present.
• Situational (S) segments are included only when applicable/certain conditions are met; may use UM01 = Health Services Review (HS) and often includes more detailed service line data (e.g., SV1, SV2 (is required only if a procedure code is being submitted, that is, if the data exists or is relevant to the business scenario), SV3 depending on service type).
  • Example 1: Optional Segment with Required Field
    Scenario:
    The SV2 – Institutional Service Line segment is Situational (only needed if institutional service details are provided).
    SV201 (Procedure Code) is marked as R (Required) within SV2.
    Rule:
    If the SV2 segment is not used, SV201 is irrelevant (it cannot be required because the entire segment is optional).
    If SV2 is used, SV201 must be present because it is required within that segment.
    Explanation:
    Segment-level optionality overrides element-level requirement.
    Required elements only apply when the segment itself is included.
  • Example 2: Situational Element in a Required Segment
    Scenario:
    The UM – Service Review segment is Required for every patient event.
    UM02 (Certification Type Code) is S (Situational).
    Rule:
    UM segment must always appear, but UM02 only appears if the certification type is relevant (e.g., inpatient vs outpatient).
    If the condition doesn’t apply, UM02 is omitted even though the segment is mandatory.
    Explanation:
    Required segment does not force all elements to be present.
    Situational elements depend on business context.
  • Example 3: Conditional Syntax Rule
    Scenario:
    In NM1 – Subscriber Name, NM108, and NM109 have a syntax rule:
    P0809 – If NM108 is present, NM109 is required.
    Rule:
    Both NM108 and NM109 are marked R, but their presence is conditional on each other.
    If you include NM108 (ID Code Qualifier), you must include NM109 (Identification Code).
    If neither is needed (e.g., no ID provided), both can be omitted.
• These usage indicators are defined in the segment detail tables in Section 2.4 of the Implementations Guide.
• The loop structure (2000A–2000F) remains consistent, but the segment content varies based on the business scenario.
• NM1IL... = Subscriber Name (Loop 2010C).
• DMGD8... = Subscriber Demographics (DOB).
• NM11P... = Requesting Provider Name (Loop 2010B).
• UM*SC... = Service Review Information (Consultation).
• DTP_472_D8... = Service Date.

PER segment (Contact Information) is Situational—include only if contact details are needed.

Inside PER:

• PER01 (Contact Function Code) = Required (R)
• PER02 (Name) = Situational (S)
• PER03 (Communication Number) = Required (R)

Rule in practice:

• If you don’t need to send contact info, skip PER entirely.
• If you include PER, the PER01 and PER03 must be present, and PER02 only if applicable.
• If you say “Type of contact: Phone”, you must also give the phone number.
• If you say “Type of contact: Email”, you must also give the email address.
• Qualifier and value always come as a pair.

📘

Validate Against the Implementation Guide

Use the Implementation Guide to:

• Confirm segment order and loop nesting (e.g., HL segments for hierarchy).
• Validate required versus situational segments.
• Ensure correct code values (e.g., NM108 qualifiers like XX, MI, PI).
• Apply constraints from the guide’s segment usage tables and examples.

Resources

Please refer to following sections in the 5010 278 Health Care Services Inquiry and Response X215 in https://X12.org/licensing.

• Section 1.11–1.12: Explains the hierarchical data structure and provides sample configurations for loops and segments.
• Section 2.4 & 2.6: Details each segment, its elements, and usage rules.
• Section 3: Provides real-world examples of EDI 278 transactions (see pages 373–381 for sample Inquiry and Response).
• Appendix B: Explains EDI nomenclature, segment structure, and control envelopes.