API referenceProviders
Everything about an NPI in one call
GET /v1/providers/{npi}/full
GET https://api.healthcare.dev/v1/providers/{npi}/fullPro 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.
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
curl "https://api.healthcare.dev/v1/providers/1881018208/full" \
-H "Authorization: Bearer $HDEV_API_KEY"TypeScript
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
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()Try it
Response
The NPI joined across the provider datasets
{
"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). Branch on type, not on title. See 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. |