{
  "_meta": {
    "title": "NPPES NPI Registry — Refresh Cadence and Snapshot Policy",
    "description": "Documents the official CMS NPPES file refresh schedule, the NPPES API real-time vs. bulk file lag, and Fonteum's snapshot policy for the NPPES source family.",
    "source": "CMS NPPES",
    "source_url": "https://download.cms.gov/nppes/NPI_Files.html",
    "fonteum_snapshot": "2026-05-01",
    "methodology_version": "nppes-anatomy/v1"
  },
  "official_cms_refresh": {
    "full_replacement_file": {
      "frequency": "Monthly",
      "release_schedule": "The full replacement file (NPPES_Data_Dissemination_*_Full_Replacement.zip) is released on the second Monday of each month.",
      "file_naming_pattern": "NPPES_Data_Dissemination_MMDDYYYY_MMDDYYYY_Full_Replacement.zip",
      "file_size_approximate": "~6-8 GB compressed, ~30-40 GB uncompressed",
      "record_count_approximate": "~8.9 million rows (including deactivated records)",
      "source_url": "https://download.cms.gov/nppes/NPI_Files.html"
    },
    "weekly_deactivation_and_update_file": {
      "frequency": "Weekly",
      "release_schedule": "Weekly update files are released on Mondays, covering changes from the prior week.",
      "file_naming_pattern": "NPPES_Data_Dissemination_MMDDYYYY_MMDDYYYY.zip",
      "contents": "Contains additions, deactivations, and field-level changes since the prior week's file. Smaller than the full replacement file.",
      "notes": "The weekly file is useful for streaming update pipelines. It is not a complete snapshot — do not use in place of the monthly full replacement for fresh ingestions."
    },
    "nppes_api": {
      "endpoint": "https://npiregistry.cms.hhs.gov/api/",
      "version": "2.1",
      "real_time": true,
      "notes": "The NPPES API reflects the current state of the registry, which updates in near-real-time as providers enroll, update, or deactivate. API records may be minutes ahead of the weekly file and up to 30 days ahead of the monthly full replacement file.",
      "rate_limits": "CMS does not publish formal rate limits for the public API, but sustained high-volume querying may be throttled.",
      "bulk_export": false,
      "use_case": "Best for single-record lookups by NPI. Not suitable for bulk ingestion — use the downloadable files instead."
    }
  },
  "lag_analysis": {
    "monthly_full_to_api": {
      "max_lag_days": 30,
      "description": "The monthly full replacement file may be up to 30 days behind the live API state. A provider who deactivated on the 15th may appear active in a full replacement file released on the 10th of the following month."
    },
    "weekly_to_api": {
      "max_lag_days": 7,
      "description": "The weekly update file reduces lag to approximately 7 days. For most research and analytics use cases, this is acceptable. For compliance workflows requiring real-time deactivation awareness, the NPPES API should be queried directly."
    },
    "deactivation_to_record": {
      "description": "CMS deactivates NPIs when providers die, organizations disband, or deactivation is requested. The deactivation is processed administratively, which can take weeks to months after the actual cessation of practice. The weekly file typically reflects deactivations within 7 days of CMS processing — but CMS processing may lag the real-world event by weeks.",
      "practical_implication": "A provider who stopped practice in January may not appear with a deactivation date until March or April. Plan for this lag in any active-practice inference."
    }
  },
  "fonteum_snapshot_policy": {
    "ingestion_frequency": "Monthly, following the CMS monthly full replacement release",
    "snapshot_date_definition": "The date on which Fonteum ingested and attested the NPPES full replacement file. Recorded as an ISO 8601 date (YYYY-MM-DD) in the Fonteum provenance chain.",
    "current_snapshot": "2026-05-01",
    "snapshot_attestation": "Each Fonteum snapshot is Ed25519-signed. The snapshot hash and signature are published at fonteum.com/chain and can be independently verified against the original CMS download URL.",
    "freshness_sla": "Fonteum targets a maximum of 35 days between NPPES snapshot and publication. In practice, the cadence follows the CMS monthly release cycle.",
    "deactivated_record_handling": "Deactivated NPIs are retained in the Fonteum database with their deactivation date and reason code. They are not surfaced in active-provider listings but remain queryable via the API for historical research.",
    "weekly_delta_note": "Fonteum does not currently ingest the weekly NPPES delta files. The monthly full replacement is the primary source. Organizations requiring weekly deactivation tracking should query the NPPES API directly."
  },
  "version_history": [
    {
      "snapshot_date": "2026-05-01",
      "full_file_release": "NPPES_Data_Dissemination_05012026_05142026_Full_Replacement",
      "record_count": 8940000,
      "active_count": 7200000,
      "notes": "Current Fonteum production snapshot. First snapshot to include MIPS badge cross-join."
    },
    {
      "snapshot_date": "2025-12-01",
      "full_file_release": "NPPES_Data_Dissemination_12012025_12152025_Full_Replacement",
      "record_count": 8870000,
      "active_count": 7120000,
      "notes": "Prior snapshot retained for historical comparison."
    }
  ]
}