Name: NPI Healthcare Provider Search API - CMS Registry Data
Brand: cblu
SKU: api-cblu-npi-healthcare-providers
Availability: InStock
Author: API Market

# NPI Healthcare Provider Search API

## Overview
The NPI Healthcare Provider Search API provides direct access to the official US Centers for Medicare & Medicaid Services (CMS) NPPES NPI Registry. This powerful API allows developers to search over 8 million healthcare providers and organizations across the United States, including physicians, dentists, nurses, therapists, pharmacies, clinics, and hospitals. It returns comprehensive, clean, and flattened JSON records containing essential details such as the NPI number, primary specialty (taxonomy), license number and state, practice address, phone, fax, and (for organizations) the authorized official.

Leveraging live CMS data, this API eliminates the need for an NPPES key and automatically handles complexities like ZIP fan-out to overcome the CMS API's silent 1,200-record limit. Queries are executed live against the registry, ensuring the most up-to-date information.

## Features
*   **Comprehensive Search:** Access over 8 million US healthcare providers and organizations.
*   **Official Data Source:** Queries against the official CMS NPPES NPI Registry.
*   **Rich Data Fields:** Retrieve NPI number, specialty (taxonomy), license number/state, practice address, phone, fax, and authorized official for organizations.
*   **Clean JSON Output:** Returns flattened, easy-to-parse JSON records.
*   **Live Data:** Ensures up-to-date information by querying the CMS registry in real-time.
*   **No NPPES Key Required:** Simplifies access without the need for additional credentials.
*   **Advanced Search Capabilities:** Supports search by specialty, state, city, postal code (with wildcards), first name (with wildcards), last name (with wildcards), or organization name (with wildcards).
*   **Automatic ZIP Fan-Out:** Bypasses the CMS API's 1,200-record cap by automatically fanning out ZIP code queries.
*   **Flexible Result Limits:** Specify `maxResults` to control the number of records returned (up to 100 per call).
*   **Synchronous Processing:** Get immediate results directly in the API response.

## Use Cases
*   **Healthcare Provider Directories:** Power online directories with up-to-date contact information, specialties, and license details for healthcare professionals and facilities. This enhances user experience and ensures data accuracy for patients seeking care.
*   **Medical Credentialing and Verification:** Automate the verification of provider credentials, licenses, and NPI status for compliance, onboarding new practitioners, or maintaining existing provider networks within insurance companies or healthcare systems.
*   **Market Research and Analytics:** Analyze healthcare provider distribution, specialty concentrations, and organizational presence across different geographic regions for strategic planning, market expansion, or competitive intelligence in the pharmaceutical and medical device industries.
*   **Healthcare Technology Solutions:** Integrate robust provider search capabilities into Electronic Health Record (EHR) systems, telehealth platforms, or patient management software, enabling users to quickly identify and connect with relevant healthcare professionals.
*   **Insurance Claims Processing:** Validate NPI numbers and provider details during claims submission and processing to reduce errors, prevent fraud, and ensure accurate reimbursement for healthcare services.

## API Documentation

### Base URL
All API requests should be made to: `https://prod.api.market/api/v1/cblu/npi-healthcare-providers`

### Authentication
Authentication is handled via API key. Include your API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```
### Endpoints

#### Search US healthcare providers (NPPES NPI Registry)
`POST /api/v1/cblu/npi-healthcare-providers/acts/cblu~npi-healthcare-providers-scraper/run-sync-get-dataset-items`

Runs a live search against the CMS NPPES registry and returns matching provider records as a JSON array. Provide at least one of `taxonomyDescription`, `state`, `city`, `postalCode`, `firstName`, `lastName`, or `organizationName`.

**Request Parameters:**
*   `clean` (Query, optional, boolean, default: `true`): Return clean dataset items only (recommended).
*   `format` (Query, optional, string, enum: `json`, `csv`, default: `json`): Response format.

**Request Body (application/json):**
Schema: `ProviderSearchInput` (At least one search criterion is required)
| Property | Type | Description | Example |
| :------- | :--- | :---------- | :------ |
| `taxonomyDescription` | string | Specialty / taxonomy description, e.g. "Dentist", "Family Medicine". Exact taxonomy codes also work. | "Dentist" |
| `state` | string | Two-letter US state code of the practice location. `^[A-Za-z]{2}$` | "TX" |
| `city` | string | Practice-location city. | "Austin" |
| `postalCode` | string | Practice-location ZIP. Prefix wildcards supported: "331*" matches all ZIPs starting with 331. | "331*" |
| `enumerationType` | string | "individual" (NPI-1) or "organization" (NPI-2). Omit for both. | "individual" |
| `firstName` | string | Provider first name (individuals). Trailing wildcard supported, e.g. "jo*". | "John*" |
| `lastName` | string | Provider last name (individuals). Trailing wildcard supported. | "Doe*" |
| `organizationName` | string | Organization name (NPI-2). Trailing wildcard supported, e.g. "mayo*". | "Mayo Clinic*" |
| `maxResults` | integer | Maximum provider records to return in this call. Minimum: 1, Maximum: 100. Default: 50. | 50 |

**Example Request Body (Dentists in greater Miami):**
```json
{
  "taxonomyDescription": "Dentist",
  "postalCode": "331*",
  "maxResults": 50
}
```

**Response (200 OK or 201 Created - application/json):**
Schema: `array` of `Provider` objects
An array of matching provider records. Each `Provider` object includes details like:
| Property | Type | Description |
| :------- | :--- | :---------- |
| `npi` | string | 10-digit National Provider Identifier (stable unique key). |
| `enumerationType` | string | individual (NPI-1) or organization (NPI-2). |
| `name` | string \| null | Provider full name or organization name. |
| `credential` | string \| null | Credential, e.g. MD, DDS, RN. |
| `gender` | string \| null | |
| `soleProprietor` | string \| null | |
| `organizationalSubpart` | string \| null | |
| `status` | string \| null | ACTIVE for active NPIs. |
| `enumerationDate` | string \| null | Date the NPI was assigned. |
| `lastUpdated` | string \| null | Date the record was last updated in NPPES. |
| `specialty` | string \| null | Primary taxonomy description. |
| `licenseNumber` | string \| null | License number of the primary taxonomy. |
| `licenseState` | string \| null | License state of the primary taxonomy. |
| `taxonomies` | array | All taxonomies (specialties) with license details. |
| `practiceAddress` | object \| null | Primary practice location with phone and fax. |
| `mailingAddress` | object \| null | |
| `additionalPracticeLocations` | array | Secondary practice locations. |
| `authorizedOfficial` | object \| null | Authorized official (organizations only). |
| `otherNames` | array | |
| `identifiers` | array | Other identifiers (Medicaid, insurer IDs) on the record. |
| `npiUrl` | string | Direct NPPES registry URL of the provider. |

**Example Response:**
```json
[
  {
    "npi": "1234567890",
    "enumerationType": "individual",
    "name": "JOHN DOE",
    "credential": "DDS",
    "gender": "M",
    "soleProprietor": null,
    "organizationalSubpart": null,
    "status": "ACTIVE",
    "enumerationDate": "2007-01-01",
    "lastUpdated": "2023-10-26",
    "specialty": "Dentist",
    "licenseNumber": "D12345",
    "licenseState": "FL",
    "taxonomies": [
      {
        "code": "122300000X",
        "description": "Dentist",
        "primary": true,
        "license": "D12345",
        "licenseState": "FL"
      }
    ],
    "practiceAddress": {
      "street": "123 MAIN ST",
      "city": "MIAMI",
      "state": "FL",
      "zip": "33133-1234",
      "country": "US",
      "phone": "3051234567",
      "fax": null
    },
    "mailingAddress": {
      "street": "123 MAIN ST",
      "city": "MIAMI",
      "state": "FL",
      "zip": "33133-1234",
      "country": "US",
      "phone": null,
      "fax": null
    },
    "additionalPracticeLocations": [],
    "authorizedOfficial": null,
    "otherNames": [],
    "identifiers": [],
    "npiUrl": "https://npiregistry.cms.hhs.gov/provider-view/1234567890"
  },
  {
    "npi": "9876543210",
    "enumerationType": "organization",
    "name": "MIAMI DENTAL GROUP",
    "credential": null,
    "gender": null,
    "soleProprietor": null,
    "organizationalSubpart": null,
    "status": "ACTIVE",
    "enumerationDate": "2010-05-15",
    "lastUpdated": "2023-11-01",
    "specialty": "General Practice Dentistry",
    "licenseNumber": null,
    "licenseState": null,
    "taxonomies": [
      {
        "code": "1223G0001X",
        "description": "General Practice Dentistry",
        "primary": true,
        "license": null,
        "licenseState": null
      }
    ],
    "practiceAddress": {
      "street": "456 OAK AVE",
      "city": "MIAMI BEACH",
      "state": "FL",
      "zip": "33139-5678",
      "country": "US",
      "phone": "3059876543",
      "fax": "3059876544"
    },
    "mailingAddress": {
      "street": "456 OAK AVE",
      "city": "MIAMI BEACH",
      "state": "FL",
      "zip": "33139-5678",
      "country": "US",
      "phone": null,
      "fax": null
    },
    "additionalPracticeLocations": [],
    "authorizedOfficial": {
      "name": "JANE SMITH",
      "title": "CEO",
      "phone": "3059876543"
    },
    "otherNames": [],
    "identifiers": [],
    "npiUrl": "https://npiregistry.cms.hhs.gov/provider-view/9876543210"
  }
]
```

## Status Codes
*   **200 OK:** Request successful. The API has processed the request and returned the expected data.
*   **201 Created:** Matching provider records (returned by some gateway configurations). This indicates success, similar to 200 OK.
*   **400 Bad Request:** Invalid input parameters or malformed request. This typically occurs if required search criteria are missing or if parameters like `state` or `postalCode` have an invalid format. Review your request body and query parameters against the schema.
*   **401 Unauthorized:** Missing or invalid API key. Ensure your `x-api-market-key` header is correctly provided.
*   **403 Forbidden:** Valid API key but insufficient permissions. Your API key might not have access to this specific API.
*   **404 Not Found:** Resource not found. This typically means the API endpoint path is incorrect.
*   **408 Request Timeout:** The query did not finish within the 300-second synchronous limit. This can happen with very broad searches. Narrow your search criteria (e.g., add a specific city, specialty, or part of a name) to reduce the volume of data processed.
*   **429 Too Many Requests:** Rate limit exceeded. You have sent too many requests in a given time frame. Implement back-off and retry logic.
*   **500 Internal Server Error:** A server-side error occurred. This is usually an issue on the API provider's end. If it persists, contact support.
*   **503 Service Unavailable:** The service is temporarily unavailable, likely due to maintenance or high load. Implement a retry mechanism with increasing delays.

## Rate Limits
Specific rate limits are applied to prevent abuse and ensure fair usage for all users. If you exceed the rate limits, you will receive a `429 Too Many Requests` status code. It is recommended to implement exponential back-off and retry logic in your client applications to gracefully handle these situations.

## Error Handling
Effective error handling is crucial for building robust applications.
*   **Interpret Error Responses:** Always check the HTTP status code of the API response. For non-2xx status codes, inspect the response body for detailed error information, which will typically be in JSON format.
*   **Common Errors:**
    *   `400 Bad Request`: Often due to missing required parameters (e.g., no search criteria in the request body) or incorrect data types/formats. Review the API schema and examples carefully.
    *   `401 Unauthorized`: Verify your `x-api-market-key` is correct and present in the request header.
    *   `408 Request Timeout`: As this API queries live data and can be time-consuming, ensure your search criteria are sufficiently narrow. Consider adding more filters like `state`, `city`, or a more specific `postalCode` or `taxonomyDescription`.
*   **Retry Strategies:** For transient errors (`429 Too Many Requests`, `503 Service Unavailable`, or `500 Internal Server Error` if it's intermittent), implement a retry mechanism. Use exponential back-off, where the delay between retries increases with each attempt, to avoid overwhelming the API. Limit the total number of retries and implement a circuit breaker pattern if errors persist.

**Example Error Response:**
```json
{
  "error": {
    "code": "invalid_input",
    "message": "At least one search criterion (specialty, state, city, postal code, or a name) must be provided.",
    "status": 400
  }
}
```



### Performance Optimization
*   **Narrow Your Search:** The API performs live queries. To optimize response times and avoid `408 Request Timeout` errors, always provide the most specific search criteria possible. Avoid overly broad queries (e.g., searching for "Physician" across an entire state without a city or ZIP code).
*   **Batch Requests Strategically:** If you need to retrieve a large number of records, consider breaking down your requests by specific criteria (e.g., iterating through ZIP codes within a larger area) and managing these individual synchronous calls rather than attempting a single, extremely broad query.
*   **Utilize `maxResults`:** Use the `maxResults` parameter to limit the number of records returned per call, which can help manage payload size and processing time, especially if you only need a sample. The maximum allowed is 100 records per call.
*   **Cache Results:** For frequently accessed or relatively static data, implement a caching mechanism on your side to reduce redundant API calls and improve application responsiveness. The `lastUpdated` field in the `Provider` object can help determine when cached data might need refreshing.

## FAQ
**Q: What is an NPI number?**

A: An NPI (National Provider Identifier) is a unique 10-digit identification number issued to health care providers in the United States by the CMS. It's used for administrative and financial transactions.

**Q: Is an NPPES key required to use this API?**

A: No, this API handles the interaction with the CMS NPPES registry directly, so you do not need your own NPPES key.

**Q: How up-to-date is the data?**

A: The API queries the CMS NPPES registry live, ensuring you receive the most current information available in the official database at the time of your request.

**Q: What happens if my search is too broad?**

A: If a search is too broad, it might result in a `408 Request Timeout` if it exceeds the 300-second processing limit. To prevent this, narrow your search criteria by adding more specific details like `city`, more precise `postalCode` (or specific 5-digit ZIPs), or a more focused `taxonomyDescription`.

**Q: What is the maximum number of results I can get per call?**

A: You can retrieve a maximum of 100 provider records per API call using the `maxResults` parameter.

**Q: Can I search using wildcards?**

A: Yes, you can use prefix wildcards for `postalCode` (e.g., "331*") and trailing wildcards for `firstName`, `lastName`, and `organizationName` (e.g., "John*", "Mayo*").

**Q: Does this API support searching by NPI number?**

A: The API is primarily designed for searching based on demographic and specialty criteria. To search by a specific NPI number, you would typically use the NPI Registry's direct lookup function (which this API abstracts for broader searches).

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Search the official US NPPES NPI Registry for 8M+ healthcare providers. Access live CMS data including NPIs, specialties, licenses, and practice addresses witho

NPI Healthcare Provider Search API - CMS Registry Data

Free

CBLU

Basic

Ultra

Search 8M+ US healthcare providers from the official NPPES NPI Registry, with live CMS data and automatic ZIP fan-out to bypass the 1,200-record limit.