# Everything about an NPI in one call URL: https://docs.healthcare.dev/reference/providers/everything-about-an-npi-in-one-call ```http GET https://api.healthcare.dev/v1/providers/{npi}/full ``` Pro plan and up (403 `plan-upgrade-required` below Pro). One NPI joined across every published provider dataset, looked up together and billed as one call: who it is (`provider`: name, entity type, active or deactivated, dates), its taxonomies with the primary one and NUCC names (`taxonomy`), the practice location (`location`), Medicare enrollment (`enrollment`: `enrolled` and the PECOS enrollments listing the NPI), Medicare opt-out (`opt_out`: `opted_out` today and the affidavit in effect) and OIG exclusions (`exclusion`: `exclusion_recorded`, matched by NPI as listed in the OIG file, and the records). The checks answer exactly as `/enrollment`, `/opt-out` and `/exclusions` do, notes included: most OIG records carry no NPI, so no exclusion recorded with this NPI never means the provider is not excluded. Each component has its own `source` (dataset, `data_version`, `as_of`) and a `status`: `available`, `not_listed` (the dataset lists nothing for this NPI; `reason` says what that means) or `unavailable` (not published or not licensed: unknown, never false). `missing` lists every component without data and why; `flags` are null when their dataset is unavailable. `conflicts` lists facts NPPES and the PECOS enrollment file both state and disagree on (a deactivated NPI still enrolled, entity type, legal business name, last name, practice state), after normalizing case, punctuation, spacing and legal form; each lists every source's value with its version, `as_of` and links, and none is chosen. `conflicts_checked` says which comparisons ran, so an empty `conflicts` means compared and none found. `view=compact` returns identity, primary taxonomy, location, the flags, `exclusion_note`, `missing`, `conflicts` and `conflicts_checked`. 404 when the provider source has no record of the NPI. Reference data, not a credentialing decision. Requires an API key: `Authorization: Bearer hdev_live_...`. See [Authentication](/authentication). ## Path parameters | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `npi` | string | yes | 10-digit National Provider Identifier | `1881018208` | ## Query parameters | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `view` | "compact" \| "standard" \| "full" | no | How much of each record to return (default `full`). `compact`: `npi`, `name`, `entity_type`, `status`, `primary_taxonomy`, `practice_location`, `flags`, `exclusion_note`, `missing`, `conflicts`, `conflicts_checked` (fewest tokens, for agents). `standard`: every field. `full`: every field. | `compact` | | `fields` | string | no | Comma-separated fields to return instead of a view. Valid fields: `npi`, `name`, `entity_type`, `status`, `primary_taxonomy`, `practice_location`, `flags`, `exclusion_note`, `missing`, `conflicts`, `conflicts_checked`, `provider`, `taxonomy`, `location`, `enrollment`, `opt_out`, `exclusion`, `exclusion_matches`. | `npi,name,entity_type` | ## Examples **curl** ```sh curl "https://api.healthcare.dev/v1/providers/1881018208/full" \ -H "Authorization: Bearer $HDEV_API_KEY" ``` **TypeScript** ```ts const res = await fetch("https://api.healthcare.dev/v1/providers/1881018208/full", { headers: { Authorization: `Bearer ${process.env.HDEV_API_KEY}` }, }); const { data, meta } = await res.json(); ``` **Python** ```python import os import requests res = requests.get("https://api.healthcare.dev/v1/providers/1881018208/full", headers={"Authorization": f"Bearer {os.environ['HDEV_API_KEY']}"}) body = res.json() ``` ## Response The NPI joined across the provider datasets ```json { "data": { "npi": "string", "name": "string", "entity_type": "individual", "status": "active", "primary_taxonomy": { "code": "string", "name": "string" }, "practice_location": { "city": "string", "state": "string", "postal_code": "string" }, "flags": { "medicare_enrolled": true, "opted_out": true, "exclusion_recorded": true, "possible_exclusion_match": true }, "exclusion_note": "string", "missing": [ { "component": "provider", "status": "not_listed", "reason": "string" } ], "conflicts": [ { "field": null, "kind": null, "description": "string", "sources": [ null ] } ], "conflicts_checked": [ { "field": null, "sources": [ null ] } ], "provider": { "status": "available", "reason": "string", "source": { "dataset": "string", "source": "string", "source_url": "string", "source_sha256": "string", "data_version": "string", "pipeline_version": "string", "license": "string", "license_terms": null, "as_of": "2026-10-01", "published_at": "2026-10-24T12:00:00Z" }, "data": { "npi": "string", "entity_type": "individual", "name": { "display": null, "first": null, "middle": null, "last": null, "prefix": null, "suffix": null, "credential": null, "organization": null }, "status": "active", "enumeration_date": "2026-10-01", "last_updated": "2026-10-01", "deactivation_date": "2026-10-01", "reactivation_date": "2026-10-01" } }, "taxonomy": { "status": "available", "reason": "string", "source": { "dataset": "string", "source": "string", "source_url": "string", "source_sha256": "string", "data_version": "string", "pipeline_version": "string", "license": "string", "license_terms": null, "as_of": "2026-10-01", "published_at": "2026-10-24T12:00:00Z" }, "data": { "primary": { "code": null, "display": null, "primary": null, "license": null, "license_state": null }, "taxonomies": [ null ], "names_source": { "dataset": null, "source": null, "source_url": null, "source_sha256": null, "data_version": null, "pipeline_version": null, "license": null, "license_terms": null, "as_of": null, "published_at": null } } }, "location": { "status": "available", "reason": "string", "source": { "dataset": "string", "source": "string", "source_url": "string", "source_sha256": "string", "data_version": "string", "pipeline_version": "string", "license": "string", "license_terms": null, "as_of": "2026-10-01", "published_at": "2026-10-24T12:00:00Z" }, "data": { "address": { "purpose": null, "line1": null, "line2": null, "city": null, "state": null, "postal_code": null, "country": null, "phone": null, "fax": null, "geo": null } } }, "enrollment": { "status": "available", "reason": "string", "source": { "dataset": "string", "source": "string", "source_url": "string", "source_sha256": "string", "data_version": "string", "pipeline_version": "string", "license": "string", "license_terms": null, "as_of": "2026-10-01", "published_at": "2026-10-24T12:00:00Z" }, "data": { "enrolled": true, "note": "string", "enrollments": [ null ], "link": "string" } }, "opt_out": { "status": "available", "reason": "string", "source": { "dataset": "string", "source": "string", "source_url": "string", "source_sha256": "string", "data_version": "string", "pipeline_version": "string", "license": "string", "license_terms": null, "as_of": "2026-10-01", "published_at": "2026-10-24T12:00:00Z" }, "data": { "opted_out": true, "note": "string", "affidavit": { "id": null, "npi": null, "name": null, "specialty": null, "opt_out_effective_date": null, "opt_out_end_date": null, "eligible_to_order_and_refer": null, "address": null, "last_updated": null, "status": null, "effective_start": null, "effective_end": null, "replaced_by": null }, "in_effect": true, "affidavits_listed": 1, "link": "string" } }, "exclusion": { "status": "available", "reason": "string", "source": { "dataset": "string", "source": "string", "source_url": "string", "source_sha256": "string", "data_version": "string", "pipeline_version": "string", "license": "string", "license_terms": null, "as_of": "2026-10-01", "published_at": "2026-10-24T12:00:00Z" }, "data": { "exclusion_recorded": true, "matched_by": "npi_as_listed", "note": "string", "exclusions": [ null ], "link": "string" } }, "exclusion_matches": { "status": "available", "reason": "string", "source": { "dataset": "string", "source": "string", "source_url": "string", "source_sha256": "string", "data_version": "string", "pipeline_version": "string", "license": "string", "license_terms": null, "as_of": "2026-10-01", "published_at": "2026-10-24T12:00:00Z" }, "data": { "possible_match": true, "note": "string", "matches": [ null ] } } }, "meta": { "source": "cms-icd10", "data_version": "2026.1", "retrieved_at": "2026-10-24T12:00:00Z", "license": "Public domain (CMS). Reference data, not medical advice." }, "links": { "self": "/v1/providers/1881018208/full", "next": null } } ``` ### Fields | Field | Type | Always present | Description | | --- | --- | --- | --- | | `npi` | string | yes | | | `name` | string | yes | Provider or organization name as CMS lists it | | `entity_type` | "individual" \| "organization" \| null | yes | null for deactivated NPIs: CMS publishes only the NPI and its dates | | `status` | "active" \| "deactivated" | yes | | | `primary_taxonomy` | object \| null | yes | The primary taxonomy; null when the NPI lists none | | `practice_location` | object \| null | yes | Where the practice location is; null when CMS lists none | | `flags` | object | yes | Yes/no answers; null means the data to answer isn't available (see `missing`) | | `exclusion_note` | string \| null | yes | How exclusions are matched (by NPI as listed in the OIG file), in plain words: show it with `exclusion_recorded`. null when exclusion data is unavailable | | `missing` | object[] | yes | Every component without data, and why; empty when every component answered | | `conflicts` | ProviderConflict[] | yes | Facts two provider sources both state and disagree on (NPPES vs the PECOS enrollment file), each with both values, sources and links. We never pick a winner. Empty means the comparisons in `conflicts_checked` ran and found no disagreement; a fact not in `conflicts_checked` wasn't compared (a source unavailable or not listing the NPI, or the fact missing on one side), so no conflict there means nothing | | `conflicts_checked` | ProviderConflictCheck[] | yes | Every comparison that ran for this NPI, conflict or not: the field and the datasets compared | | `provider` | ProviderFullIdentityComponent | yes | Who the NPI is: name, entity type, status and dates (CMS NPPES, or the NPI Registry until the NPPES file is published) | | `taxonomy` | ProviderFullTaxonomyComponent | yes | Taxonomies (specialties) listed for the NPI, with NUCC names when that code set is served | | `location` | ProviderFullLocationComponent | yes | The practice location address | | `enrollment` | ProviderFullEnrollmentComponent | yes | Medicare fee-for-service enrollment (CMS PECOS public enrollment file) | | `opt_out` | ProviderFullOptOutComponent | yes | Medicare opt-out (CMS Opt Out Affidavits file) | | `exclusion` | ProviderFullExclusionComponent | yes | Exclusions recorded with the NPI in the HHS OIG List of Excluded Individuals/Entities (LEIE), matched by NPI as listed | | `exclusion_matches` | ProviderFullExclusionMatchesComponent | yes | Possible matches, derived: OIG exclusion records that list no NPI and may belong to this provider (exact name and state, scored on middle name, address and specialty; never date of birth). Ambiguous ones are shown only after review. Not a finding of exclusion | ## Errors Errors are `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)). Branch on `type`, not on `title`. See [Errors](/errors). | Status | `type` | When | | --- | --- | --- | | 400 | `invalid-request` | A parameter or the body failed validation; `errors` lists each field. | | 401 | `unauthorized` | Missing, malformed or revoked API key. | | 403 | `plan-upgrade-required` | The plan doesn't include this feature; `required_plan` names the plan that does. | | 404 | `not-found` | No record with that id (retired records are still returned). | | 429 | `rate-limited / quota-exceeded` | Too many requests per second (retry after `Retry-After`), or the monthly quota is used up. | | 503 | `dataset-unavailable / unavailable` | The dataset has no published version yet, or the service is degraded. |