How to read an in-network rate file: a field-by-field walkthrough

In-network rate files follow a schema published by CMS. Once you know the shape, every carrier's file reads the same way, even if each one stretches the rules a little. Here's a walkthrough of the fields that matter.

The top level

{
  "reporting_entity_name": "Example Health Plan",
  "reporting_entity_type": "health insurance issuer",
  "last_updated_on": "2026-10-01",
  "version": "1.0.0",
  "provider_references": [ ... ],
  "in_network": [ ... ]
}

• reporting_entity_name / reporting_entity_type: who published the file, usually the insurer or third-party administrator.
• last_updated_on: the date the file was refreshed. Plans must update monthly.
• provider_references: a lookup table of provider groups, described below.
• in_network: the list of covered services and their rates. This is where almost all the data lives.

Provider references

Rates rarely list providers inline. Instead, each rate points to one or more IDs in provider_references:

"provider_references": [
  {
    "provider_group_id": 42,
    "provider_groups": [
      {
        "npi": [1234567890, 1987654321],
        "tin": { "type": "ein", "value": "12-3456789" }
      }
    ]
  }
]

Each provider group is a TIN and the NPIs that bill under it. Some carriers keep these references in separate files and link to them by URL, so a parser has to fetch them before it can tell who a rate belongs to.

Covered services

Each entry in in_network is one billing code:

{
  "negotiation_arrangement": "ffs",
  "name": "MRI BRAIN W/O CONTRAST",
  "billing_code_type": "CPT",
  "billing_code_type_version": "2026",
  "billing_code": "70551",
  "description": "Magnetic resonance imaging, brain; without contrast",
  "negotiated_rates": [ ... ]
}

• negotiation_arrangement: ffs (fee-for-service), bundle or capitation. Most rates are fee-for-service.
• billing_code_type: CPT, HCPCS, MS-DRG, revenue code and others.

Negotiated rates

"negotiated_rates": [
  {
    "provider_references": [42],
    "negotiated_prices": [
      {
        "negotiated_type": "negotiated",
        "negotiated_rate": 538.00,
        "expiration_date": "9999-12-31",
        "service_code": ["11", "22"],
        "billing_class": "professional",
        "billing_code_modifier": ["26"]
      }
    ]
  }
]

This is the heart of the file:

• negotiated_type: negotiated (a dollar amount), derived, fee schedule, percentage or per diem. A percentage rate is a share of billed charges, not dollars. Don't average it with dollar amounts.
• negotiated_rate: the number itself.
• billing_class: professional (the clinician) or institutional (the facility). A full procedure often has both, billed separately.
• service_code: the place-of-service codes the rate applies to, such as 11 (office) or 22 (outpatient hospital).
• billing_code_modifier: modifiers that change what's being paid for. Modifier 26, for example, is the professional component of an imaging study.

Common pitfalls

1. Comparing across settings. The same CPT code can have very different rates in an office and a hospital outpatient department. Always compare within the same place of service.
2. Mixing professional and facility fees. A facility rate and a professional rate for the same code are two halves of one bill, not two competing prices.
3. Ignoring modifiers. A professional-component-only rate (modifier 26) will look much cheaper than a global rate.
4. Double counting. The same rate appears across many plans and files that share a network. De-duplicate before you count anything.
5. Placeholder values. Some files include rates that are clearly not real prices, like $0.01 or $999,999. Filter outliers before you publish statistics.

Next steps

Reading one file is a good way to learn. Reading every file from every carrier, every month, is an infrastructure problem, and it's the one we've built US Health.io to solve. Learn more about MRF files, or see who uses the data.