---
title: "Read CMS QPP MIPS scores for one NPI"
method: GET
path: "/api/v1/qpp-mips/{npi}"
tags: ["Providers"]
---

# Read CMS QPP MIPS scores for one NPI

`GET /api/v1/qpp-mips/{npi}`

## Request

- Base URL: `https://fonteum.com`
- URL: `https://fonteum.com/api/v1/qpp-mips/{npi}`
- Auth: HTTP bearer

Returns the CMS-published MIPS final score, four category scores, and participation type for each loaded performance year, newest first. The production table has no populated payment-adjustment percentage field, so this contract does not advertise or emit one. `found=false` means no row is present in the data Fonteum currently holds; it does not establish that the clinician did not participate. Re-confirm consequential use at qpp.cms.gov.

## Path parameters

- `npi` string, required

## Query parameters

- `max_staleness` string
- `max_staleness_mode` 'flag' | 'reject'

## Response `200`

Loaded QPP MIPS history for the NPI, or found=false when no row is present.

- object
  - `data` object, required
    - `npi` string, required
    - `found` boolean, required
    - `latest` QppMipsScore, required: CMS QPP MIPS scores for one performance year. Scores can be null when CMS did not publish that category for the row.
      - `performance_year` integer, required
      - `final_score` number, nullable, required
      - `category_scores` object, required
        - `quality` number, nullable, required
        - `cost` number, nullable, required
        - `improvement_activities` number, nullable, required
        - `promoting_interoperability` number, nullable, required
      - `participation_type` string, nullable, required
    - `history` QppMipsScore[], required
      - `performance_year` integer, required
      - `final_score` number, nullable, required
      - `category_scores` object, required
        - `quality` number, nullable, required
        - `cost` number, nullable, required
        - `improvement_activities` number, nullable, required
        - `promoting_interoperability` number, nullable, required
      - `participation_type` string, nullable, required
  - `provenance` object, required: CMS QPP source, source URL, performance-year snapshot, methodology, license, coverage period, and serve-time fields available from the shared provenance builder.
  - `disclaimer` string, required
  - `meta` object, required
    - `api_version` 'v1', required
    - `freshness` FreshnessBlock[], required
      - `source_id` string, required
      - `snapshot` string, date, nullable, required: Source publication date; null when unavailable (state then `unknown`).
      - `last_checked` string, date-time, required: Serve-time — the only `now` field.
      - `sla_days` integer, nullable
      - `sla_hours` integer, nullable
      - `age_hours` integer, nullable
      - `age_days` integer, nullable
      - `within_sla` boolean, nullable
      - `state` 'current' | 'degraded' | 'stale' | 'unknown', required
    - `freshness_policy` FreshnessPolicy: Present only when the request set `max_staleness`. Reports whether each consulted stored source observation met the caller's age bar; it does not assert that the upstream publisher released newer data.
      - `requested` true, required
      - `max_staleness` string, required
      - `max_staleness_hours` number, required
      - `mode` 'flag' | 'reject', required
      - `stale` boolean, required
      - `stale_sources` object[], required
        - `source_id` string
        - `state` 'current' | 'degraded' | 'stale' | 'unknown'
        - `age_hours` integer, nullable
        - `reason` 'exceeds_max_staleness' | 'freshness_unknown'
    - `methodology_url` string, uri, required
    - `documentation_url` string, uri, required

## Other responses

- `400`: NPI is not exactly 10 digits, or max_staleness is malformed.
- `401`: Missing or invalid API key.
- `409`: A consulted stored source observation is behind the caller's `max_staleness` bar and `max_staleness_mode=reject` was set. The body still carries `data` + `meta.freshness_policy` (which observations failed and why); the read is not presented as meeting the configured age bar.
- `429`: Rate limit exceeded.
- `500`: CMS QPP MIPS lookup failed.
- `503`: Rate-limit storage is temporarily unavailable.

---

[API](https://skmtc.dev/fonteum/apis/fonteum-api.md) · [All operations](https://skmtc.dev/fonteum/apis/fonteum-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fonteum/apis/fonteum-api/revisions/334e6e179d0d?raw)