---
title: "Cross-dataset entity resolution by NPI"
method: GET
path: "/api/v1/npi/{npi}"
tags: ["NpiEntityResolution"]
---

# Cross-dataset entity resolution by NPI

`GET /api/v1/npi/{npi}`

## Request

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

Returns the source blocks available for an NPI from NPPES, OIG LEIE, PECOS, QPP MIPS, CMS Open Payments, and SAM.gov. A block can be absent, and provenance fields within a block can be null. Exclusion booleans are nullable: a no-match is emitted only when the internal coverage guard reports reconciled `current`; that state does not assert same-day upstream freshness. Stale or unreconciled coverage returns `determination: indeterminate` and is not a clearance.

Requires `Authorization: Bearer fnt_...` and uses the key's configured limits.

Caching: `Cache-Control: no-store`; a newer comparable exclusion artifact can invalidate a prior negative immediately.

## Path parameters

- `npi` string, required

## Query parameters

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

## Response `200`

Resolved provider record with the available source blocks and nullable per-source provenance fields.

- object
  - `data` object
    - `npi` string
    - `resolved_at` string, date-time
    - `authenticated` boolean
    - `sources` object: One block per supported federal source. A block exposes `data` (null if not found / not ingested) and a nullable `provenance` object; populated values vary by source and response. Sources: nppes, oig_leie, pecos, qpp_mips, open_payments, sam_gov.
    - `composite` object
      - `active_and_clean` boolean, nullable: Null when exclusion coverage is stale or indeterminate; never true without current coverage.
      - `sources_resolved` integer
      - `field_confidence_min` number
      - `_methodology` string
    - `exclusion_screen` object
      - `excluded` boolean, nullable
      - `compromised_anywhere` boolean, nullable
      - `coverage` ExclusionCoverage
        - `status` 'current' | 'coverage_stale' | 'indeterminate', required
        - `sources` object, required
        - `message` string, required
      - `coverage_status` 'current' | 'coverage_stale' | 'indeterminate'
      - `determination` 'match' | 'no_match' | 'indeterminate'
  - `meta` ResponseMeta
    - `request_id` string, required
    - `api_version` 'v1', required
    - `data_freshness` union, required: One source block or an array of source blocks. Fields keep content-change, publisher-release, artifact-snapshot, coverage, check, and observation timestamps separate; only a proved canonical content transition can make last_refreshed non-null.
      - DataFreshness
        - `source` string, required
        - `last_refreshed` string, date-time, nullable, required: Timestamp of the most recent proved content change. Null when canonical content evidence is unavailable, invalid, or conflicted.
        - `source_release_date` string, date-time, nullable: Publisher-issued release date represented by the response. Coverage and static artifact dates use their own fields and never advance last_refreshed.
        - `artifact_snapshot_date` string, date-time, nullable: Fonteum or static aggregate artifact snapshot represented by the response; not a publisher release or content-change timestamp.
        - `coverage_date` string, date-time, nullable: Source-data coverage date or period boundary; not a publisher release or content-change timestamp.
        - `last_checked_at` string, date-time, nullable: Latest workflow or source check, separate from content freshness.
        - `last_observed_at` string, date-time, nullable: Latest source_snapshots ledger observation, separate from content freshness.
        - `timestamp_basis` 'content_change', nullable: Present only when last_refreshed is backed by a proved canonical content transition.
        - `evidence_status` 'proved' | 'unavailable' | 'invalid' | 'conflicted' | 'error'
        - `next_refresh_eta` string, date-time, nullable
        - `cadence` string
      - DataFreshness[]
        - `source` string, required
        - `last_refreshed` string, date-time, nullable, required: Timestamp of the most recent proved content change. Null when canonical content evidence is unavailable, invalid, or conflicted.
        - `source_release_date` string, date-time, nullable: Publisher-issued release date represented by the response. Coverage and static artifact dates use their own fields and never advance last_refreshed.
        - `artifact_snapshot_date` string, date-time, nullable: Fonteum or static aggregate artifact snapshot represented by the response; not a publisher release or content-change timestamp.
        - `coverage_date` string, date-time, nullable: Source-data coverage date or period boundary; not a publisher release or content-change timestamp.
        - `last_checked_at` string, date-time, nullable: Latest workflow or source check, separate from content freshness.
        - `last_observed_at` string, date-time, nullable: Latest source_snapshots ledger observation, separate from content freshness.
        - `timestamp_basis` 'content_change', nullable: Present only when last_refreshed is backed by a proved canonical content transition.
        - `evidence_status` 'proved' | 'unavailable' | 'invalid' | 'conflicted' | 'error'
        - `next_refresh_eta` string, date-time, nullable
        - `cadence` string
    - `methodology_url` string, uri, required
    - `limitations_url` string, uri, required
    - `documentation_url` string, uri
    - `geo_scope_note` string
    - `pagination` object
      - `total` integer
      - `page` integer
      - `per_page` integer
    - `freshness` FreshnessBlock[]: Typed per-source stored-observation timing: snapshot date, configured target, and a computed age state. This measures the stored observation against Fonteum's configured target, not upstream publisher freshness. A `current` state requires a dated stored snapshot; an unconfirmable date renders `unknown`.
      - `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'
    - `attestation` TrustMark, required: Re-checkable attribution attached to v1 response metadata. The chain-head value is a 32-byte content hash, not an Ed25519 signature. Per-snapshot witness signatures use a separately scoped evidence object and never occupy this contract.
      - `attested_by` 'Fonteum', required
      - `standard` 'W3C-VC-2.0', required
      - `content_credential` 'C2PA-aligned Content Credentials for facts', required
      - `source` string, nullable, required
      - `as_of` string, nullable, required
      - `attestation_id` integer, nullable, required: Snapshot id when a specific snapshot is in scope; otherwise the live chain-head link index.
      - `chain_head_hash` string, nullable, required: Current chain-head content hash. This field is deliberately not named or represented as a signature.
      - `recheck_url` string, uri, required
      - `key_url` string, uri, required: Signing-key directory used by separately exposed chain and witness evidence.
      - `docs_url` string, uri, required

## Other responses

- `400`: NPI is not exactly 10 digits, or `invalid_max_staleness` when the freshness bar is malformed.
- `404`: NPI not found in CMS NPPES NPI Registry.
- `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.
- `503`: CMS NPPES could not answer reliably because its upstream request failed or returned an invalid payload. The lookup is indeterminate, not a not-found result.

---

[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)