Fast FHIR R4 Mapping

Turquoise TEP implements a lean, purpose-built version of FHIR R4 optimized for bundled healthcare claims and deterministic pricing. We call this "Fast FHIR"—it retains FHIR's semantic clarity while eliminating unnecessary complexity and mandatory fields. This guide explains how TEP artifacts map to FHIR resources and provides real examples using Sharp HealthCare's GI procedure workflows.

Fast FHIR Principles

Fast FHIR differs from standard FHIR in three ways:

1. Minimal Required Fields: Only fields essential for claims processing and payment are mandatory. Optional FHIR fields can be omitted without validation errors.
2. Deterministic Pricing: FHIR extension fields support bundled pricing, SSP references, and provider shares. These are normalized across all TEP claims.
3. Audit Trail: Every claim includes traceability fields (claimID, claimResponseID, trace_id) linking it back to the encounter and the Stripe payment.

FHIR Resource Overview

TEP uses five core FHIR R4 resources:

FHIR Resource	TEP Usage	Key Cardinality
Claim	Professional and institutional claims submitted by providers	1 per provider per encounter
ClaimResponse	Pricing advice, payment approval, and settlement instructions from TEP/payer	1 per Claim or 1 per encounter-level bundle
ExplanationOfBenefits (EOB)	Post-payment financial summary for patient and provider	1 per encounter
Communication	GFE, AEOB, and voucher transport	1 per GFE, 1 per AEOB, 1 per voucher
Contract	Direct Contract definition (rates, SSPs, provider shares)	1 per contract

Professional Claim Example: Surgeon (CPT 45378)

A surgeon submits a professional claim for a colonoscopy with biopsy.

{
  "resourceType": "Claim",
  "id": "claim-surgeon-001",
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/claim-type",
        "code": "professional"
      }
    ]
  },
  "use": "claim",
  "patient": {
    "reference": "Patient/patient-12345"
  },
  "billablePeriod": {
    "start": "2024-03-10",
    "end": "2024-03-10"
  },
  "created": "2024-03-11T09:00:00Z",
  "enterer": {
    "reference": "Practitioner/surgeon-789"
  },
  "insurer": {
    "reference": "Organization/sharp-health-plan"
  },
  "provider": {
    "reference": "Practitioner/surgeon-789"
  },
  "facility": {
    "reference": "Location/sharp-outpatient-pavilion"
  },
  "careTeam": [
    {
      "sequence": 1,
      "provider": {
        "reference": "Practitioner/surgeon-789"
      },
      "role": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/claimcareteamrole",
            "code": "attending"
          }
        ]
      }
    }
  ],
  "diagnosis": [
    {
      "sequence": 1,
      "diagnosisCodeableConcept": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/sid/icd-10-cm",
            "code": "Z12.11",
            "display": "Encounter for screening for malignant neoplasm of colon"
          }
        ]
      }
    }
  ],
  "item": [
    {
      "sequence": 1,
      "careTeamSequence": [1],
      "diagnosisSequence": [1],
      "category": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/ex-claimitemtype",
            "code": "service"
          }
        ]
      },
      "productOrService": {
        "coding": [
          {
            "system": "http://www.ama-assn.org/go/cpt",
            "code": "45378",
            "display": "Colonoscopy, flexible; with removal of tumor(s), polyp(s), or other lesion(s) by snare technique"
          }
        ]
      },
      "servicedDate": "2024-03-10",
      "quantity": {
        "value": 1
      },
      "unitPrice": {
        "value": 1200.00,
        "currency": "USD"
      },
      "net": {
        "value": 1200.00,
        "currency": "USD"
      },
      "extension": [
        {
          "url": "http://turquoise.health/extension/sspReference",
          "valueString": "COLONOSCOPY-001"
        },
        {
          "url": "http://turquoise.health/extension/providerShare",
          "valueDecimal": 0.35
        },
        {
          "url": "http://turquoise.health/extension/bundledRate",
          "valueMoney": {
            "value": 2500.00,
            "currency": "USD"
          }
        }
      ]
    }
  ],
  "total": {
    "value": 1200.00,
    "currency": "USD"
  },
  "extension": [
    {
      "url": "http://turquoise.health/extension/claimSourceID",
      "valueString": "EHR-SHARP-GI-2024-0001"
    },
    {
      "url": "http://turquoise.health/extension/encounterID",
      "valueString": "ENC-2024-0001"
    },
    {
      "url": "http://turquoise.health/extension/directContractID",
      "valueString": "SHARP-GI-2024"
    }
  ]
}

Key Points:

• type.coding.code = "professional" indicates this is a professional (provider-submitted) claim, not an institutional one.
• provider.reference points to the specific practitioner (surgeon).
• item[].productOrService.coding.code = "45378" is the CPT code.
• item[].unitPrice = 1200.00 is the surgeon's proposed charge; this will be overridden by the contract rate.
• Extension fields (marked with http://turquoise.health/extension/) provide TEP-specific metadata:
  • sspReference indicates which Standard Service Package (SSP) this claim belongs to.
  • providerShare (0.35 = 35%) specifies the surgeon's share of the bundled rate.
  • bundledRate ($2,500) is the total SSP rate; TEP uses this to calculate the surgeon's actual payment ($2,500 × 0.35 = $875).
  • encounterID links all claims from the same encounter for bundling.
  • directContractID identifies the contract governing pricing.

Institutional Claim Example: Facility (Revenue Code 0360)

A hospital facility submits an institutional claim for the same colonoscopy encounter.

{
  "resourceType": "Claim",
  "id": "claim-facility-001",
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/claim-type",
        "code": "institutional"
      }
    ]
  },
  "use": "claim",
  "patient": {
    "reference": "Patient/patient-12345"
  },
  "billablePeriod": {
    "start": "2024-03-10",
    "end": "2024-03-10"
  },
  "created": "2024-03-11T09:00:00Z",
  "provider": {
    "reference": "Organization/sharp-outpatient-pavilion"
  },
  "facility": {
    "reference": "Location/sharp-outpatient-pavilion"
  },
  "insurer": {
    "reference": "Organization/sharp-health-plan"
  },
  "hospitalization": {
    "admitType": {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/admit-source",
          "code": "outpatient",
          "display": "Outpatient"
        }
      ]
    }
  },
  "item": [
    {
      "sequence": 1,
      "category": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/ex-revenue-center",
            "code": "0360",
            "display": "Operating/Procedure Room"
          }
        ]
      },
      "productOrService": {
        "coding": [
          {
            "system": "http://www.ama-assn.org/go/cpt",
            "code": "45378"
          }
        ]
      },
      "servicedDate": "2024-03-10",
      "quantity": {
        "value": 1
      },
      "unitPrice": {
        "value": 1000.00,
        "currency": "USD"
      },
      "net": {
        "value": 1000.00,
        "currency": "USD"
      },
      "revenue": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/ex-revenue-center",
            "code": "0360"
          }
        ]
      },
      "extension": [
        {
          "url": "http://turquoise.health/extension/sspReference",
          "valueString": "COLONOSCOPY-001"
        },
        {
          "url": "http://turquoise.health/extension/providerShare",
          "valueDecimal": 0.40
        },
        {
          "url": "http://turquoise.health/extension/bundledRate",
          "valueMoney": {
            "value": 2500.00,
            "currency": "USD"
          }
        }
      ]
    }
  ],
  "total": {
    "value": 1000.00,
    "currency": "USD"
  },
  "extension": [
    {
      "url": "http://turquoise.health/extension/claimSourceID",
      "valueString": "HB-SHARP-PAVILION-0001"
    },
    {
      "url": "http://turquoise.health/extension/encounterID",
      "valueString": "ENC-2024-0001"
    },
    {
      "url": "http://turquoise.health/extension/directContractID",
      "valueString": "SHARP-GI-2024"
    }
  ]
}

Key Differences from Professional Claim:

• type.coding.code = "institutional" indicates a facility claim.
• hospitalization.admitType.coding.code = "outpatient" is critical for bundling logic—it tells TEP this is an outpatient encounter (not an inpatient admission).
• item[].revenue (0360 = OR/Procedure Room) is mandatory for institutional claims. This revenue code is used by TEP's bundling engine to group facility charges.
• provider.reference points to the facility (organization), not an individual practitioner.

tip

AdmitType Extension: The hospitalization.admitType field is essential for TEP's bundling logic. Outpatient procedures bundle differently than inpatient episodes. Always populate this field accurately.

ClaimResponse Example: Pricing & Payment Approval

After TEP receives and validates the professional and institutional claims above, it generates a ClaimResponse (or, more commonly in TEP, a set of ClaimResponse objects—one per claim or one per encounter-level bundle).

{
  "resourceType": "ClaimResponse",
  "id": "claimresponse-enc-2024-0001",
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/claim-type",
        "code": "institutional"
      }
    ]
  },
  "use": "claim",
  "claim": {
    "reference": "Claim/claim-facility-001"
  },
  "created": "2024-03-11T09:30:00Z",
  "insurer": {
    "reference": "Organization/sharp-health-plan"
  },
  "requestProvider": {
    "reference": "Organization/sharp-outpatient-pavilion"
  },
  "outcome": "complete",
  "disposition": "Approved - Bundled pricing applied",
  "item": [
    {
      "itemSequence": 1,
      "adjudication": [
        {
          "category": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/adjudication",
                "code": "submitted"
              }
            ]
          },
          "amount": {
            "value": 1000.00,
            "currency": "USD"
          }
        },
        {
          "category": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/adjudication",
                "code": "allowable"
              }
            ]
          },
          "amount": {
            "value": 1000.00,
            "currency": "USD"
          }
        },
        {
          "category": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/adjudication",
                "code": "eligible"
              }
            ]
          },
          "amount": {
            "value": 1000.00,
            "currency": "USD"
          }
        }
      ]
    }
  ],
  "addItem": [
    {
      "itemSequence": 1,
      "provider": {
        "reference": "Practitioner/surgeon-789"
      },
      "productOrService": {
        "coding": [
          {
            "system": "http://www.ama-assn.org/go/cpt",
            "code": "45378"
          }
        ]
      },
      "adjudication": [
        {
          "category": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/adjudication",
                "code": "allowable"
              }
            ]
          },
          "amount": {
            "value": 875.00,
            "currency": "USD"
          }
        }
      ]
    },
    {
      "itemSequence": 1,
      "provider": {
        "reference": "Practitioner/anesthesia-456"
      },
      "productOrService": {
        "coding": [
          {
            "system": "http://www.ama-assn.org/go/cpt",
            "code": "00810"
          }
        ]
      },
      "adjudication": [
        {
          "category": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/adjudication",
                "code": "allowable"
              }
            ]
          },
          "amount": {
            "value": 375.00,
            "currency": "USD"
          }
        }
      ]
    },
    {
      "itemSequence": 1,
      "provider": {
        "reference": "Organization/sharp-pathology-lab"
      },
      "productOrService": {
        "coding": [
          {
            "system": "http://www.ama-assn.org/go/cpt",
            "code": "88307"
          }
        ]
      },
      "adjudication": [
        {
          "category": {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/adjudication",
                "code": "allowable"
              }
            ]
          },
          "amount": {
            "value": 250.00,
            "currency": "USD"
          }
        }
      ]
    }
  ],
  "total": [
    {
      "category": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/adjudication",
            "code": "submitted"
          }
        ]
      },
      "amount": {
        "value": 1000.00,
        "currency": "USD"
      }
    },
    {
      "category": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/adjudication",
            "code": "allowable"
          }
        ]
      },
      "amount": {
        "value": 2500.00,
        "currency": "USD"
      }
    }
  ],
  "payment": {
    "type": {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/ex-paymenttype",
          "code": "complete"
        }
      ]
    },
    "date": "2024-03-11",
    "amount": {
      "value": 2500.00,
      "currency": "USD"
    }
  },
  "extension": [
    {
      "url": "http://turquoise.health/extension/sspApplied",
      "valueString": "COLONOSCOPY-001"
    },
    {
      "url": "http://turquoise.health/extension/bundledRate",
      "valueMoney": {
        "value": 2500.00,
        "currency": "USD"
      }
    },
    {
      "url": "http://turquoise.health/extension/stripeTraceID",
      "valueString": "tfer_OPAQ0002A1B2C3D4E5F6G7H8I9J0K1L"
    },
    {
      "url": "http://turquoise.health/extension/aeobReference",
      "valueString": "AEOB-2024-0001"
    },
    {
      "url": "http://turquoise.health/extension/trueUpStatus",
      "valueString": "pending"
    }
  ]
}

Key ClaimResponse Fields:

• claim.reference links back to the original Claim.
• outcome = "complete" indicates successful processing.
• disposition explains the decision (e.g., "Approved - Bundled pricing applied").
• item[] details the itemization of the submitted claim.
• addItem[] lists all providers and their calculated allowances (surgeon $875, anesthesia $375, pathology $250).
• total[] shows submission total vs. allowable total ($2,500 bundled).
• payment provides settlement details (date, amount, method).
• Extension fields provide TEP-specific data:
  • sspApplied: Which SSP was used.
  • stripeTraceID: The opaque identifier for Stripe payment (no PHI).
  • aeobReference: Links to the AEOB that governs the cost-share cap.
  • trueUpStatus: Pending or complete (used for reconciliation after settlement).

warning

No PHI in Stripe: The stripeTraceID is an opaque, randomly generated identifier. Patient name, MRN, claim ID, and any clinical data are never transmitted to Stripe. Only opaque identifiers and dollar amounts are sent.

FHIR Field Mapping Reference

Here is a comprehensive mapping table of TEP concepts to FHIR fields:

TEP Concept	FHIR Resource	FHIR Path	Description
GFE	Claim	status = "draft"	Good Faith Estimate; not yet billed
Convened Estimate	Claim	status = "active" (pre-submission)	Updated GFE with agreed scope
AEOB	Communication + Claim	claim.supportingInfo[costShare]	Cost-share ceiling; binding forecast
Voucher	Communication	payload[].reference → Claim	Patient authorization to proceed
Professional Claim	Claim	type = "professional"	Claim from individual provider
Institutional Claim	Claim	type = "institutional"	Claim from facility/organization
SSP Reference	Claim/ClaimResponse	extension[sspReference]	Links to Standard Service Package ID
Provider Share	Claim/ClaimResponse	extension[providerShare]	Percentage of bundled rate
Bundled Rate	Claim/ClaimResponse	extension[bundledRate]	Total SSP rate
Encounter ID	Claim/ClaimResponse	extension[encounterID]	Groups all claims from one visit
Direct Contract	Contract	N/A	TEP Contract resource (custom)
Stripe Trace ID	ClaimResponse	extension[stripeTraceID]	Opaque payment identifier
True-Up Status	ClaimResponse	extension[trueUpStatus]	Reconciliation status

Bundle Anchor: Linking Claims, ClaimResponses, and Stripe Transfers

The Bundle Anchor is TEP's mechanism for tracing a dollar from encounter to settlement:

1. ClaimID (from Claim resource): Unique identifier for each submitted claim (professional, institutional, or bundled).
2. EncounterID (in Claim.extension): Groups all claims from a single visit.
3. ClaimResponseID (from ClaimResponse resource): Pricing advice and payment approval; links back to Claim(s).
4. StripeTransferID (in ClaimResponse.extension.stripeTraceID): Opaque payment identifier; links to Stripe payment batch.

The chain looks like this:

Claim-001 (Surgeon)   \
Claim-002 (Facility)  → EncounterID-2024-0001 → ClaimResponse-ENC-2024-0001 → StripeTransferID (tfer_...)
Claim-003 (Pathology) /

When auditing a payment, you can:

1. Start with the Stripe trace_id (e.g., tfer_OPAQ0002A1B2C3D4E5F6G7H8I9J0K1L).
2. Find the corresponding ClaimResponse.
3. Find the EncounterID from the ClaimResponse.
4. Find all Claims with that EncounterID.
5. Retrieve the original clinical documentation and AEOB.

This creates a complete, auditable paper trail from claim to payment to clinical encounter.

Revenue Codes for Institutional Claims

Institutional claims (facility claims) must include a revenue code for each item. Revenue codes are four-digit codes used in UB-04 billing. Common codes for outpatient services:

Revenue Code	Description	Usage
0360	OR/Procedure Room	Colonoscopy, EGD, surgery in facility
0400	ICU/Intensive Care	Inpatient monitoring
0710	Laboratory	Routine lab work
0900	Rehabilitation Services	PT, OT
0999	Other Services	Catch-all

TEP's bundling engine uses revenue codes to categorize facility charges and validate them against the SSP definition. For example, if an SSP specifies facilityRevenueCodes: ["0360"] and a claim arrives with revenue code 0710, TEP will reject the claim as out-of-scope.

info

Always populate revenue codes in institutional claims. If you don't know the correct code, use 0999. TEP will flag it and request clarification.

Next Steps

See Bundled Pricing & SSPs for more details on how rates are defined and provider shares are calculated. Then explore Fiduciary Ledger to understand the settlement and reconciliation orchestration.