# Healthcare Provider Data API - NPI Lookup, Networks, Prices (`nabeelbaghoor/healthcare-provider-data-api`) Actor Healthcare provider search and NPI lookup with the H1 API (formerly Ribbon Health): doctors by specialty, location and insurance network, care locations, health systems, insurance plans, TINs, negotiated prices and cost estimates. Bring your own key. - **URL**: https://apify.com/nabeelbaghoor/healthcare-provider-data-api.md - **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community) - **Categories:** Business, Developer tools, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $15.00 / 1,000 provider profile returneds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## Healthcare Provider Data API - NPI Lookup, Networks, Prices Search US doctors and clinicians by specialty, location and insurance network, look up full provider profiles by NPI, and pull care locations, health systems, insurance plans, TINs, negotiated prices and cost estimates from the H1 API (formerly Ribbon Health) with your own API key, as one clean dataset row per record. H1 acquired Ribbon Health, whose provider directory API is used by payers, care navigation apps and digital health companies to find in-network providers. This actor wraps the read only endpoints of that API on api.ribbonhealth.com: give a specialty and an address, a list of NPIs, or a procedure code and a ZIP code, and get deduplicated rows you can download as JSON, CSV or Excel, schedule, or feed into provider directories, network adequacy analysis, referral tools, healthcare sales prospecting, Google Sheets and AI agents. Bring your own API key. BYOK, not live-tested: every path, parameter and enum comes from the H1 API reference on ribbon.readme.io, and every route was confirmed to exist (an invalid key gets 401 on each real route and 404 on an invented one), but the actor has not been run against a live H1 key. ### What it does - **Provider search**: doctors, nurses, dentists, optometrists and other clinicians by specialty in plain words (typos and colloquial names welcome), name, provider type, gender, age, language, patient rating, procedure, condition, insurance carrier or plan, health system and distance from an address, ZIP or coordinates. Paged. - **Provider by NPI**: the full H1 profile of each 10 digit NPI: degrees, specialties with primary flags, languages, education, practice locations with address, phone and confidence score, accepting new patients, organizations, state licenses and insurance network summary. - **Location search**: hospitals, clinics, urgent care, imaging and ambulatory centers by name, location type, insurance accepted, health system, quality tier and distance. - **Organization search**: health systems by name and distance, with websites, IDs, address and phone. - **Insurance plan, TIN, specialty and procedure search**: H1 reference data, with the UUIDs the provider, location and cost estimate filters take. - **Negotiated price search (price transparency)**: payer-filed negotiated rates per facility for a CPT or HCPCS code or care cluster near an address, with minimum, median, average and maximum price per carrier, cheapest first. - **Carriers and procedure cost estimates**: the carrier IDs price search takes, and the minimum, median and maximum cost of one or more procedures near a ZIP code, from claims or price transparency data. - **Pay only for results**: refused and empty lookups are recorded as a free row that says why, never charged. Nothing is written to your H1 account: the edit, create, delete, custom filter and member eligibility endpoints are not wrapped. ### How to get an API key H1 issues API keys to customers; there is no self serve sign up. Request a demo at h1.co and ask for API access to the provider directory (and, if you need it, the price transparency module). Paste the key into the API key field, or set the DATA_API_KEY secret. The key is sent only to api.ribbonhealth.com as a Bearer token, as the documentation describes, and is removed from everything the actor logs. H1 documents that trial accounts cannot read custom provider directories; a refused module ends the run cleanly with an explanation. ### Input | Field | Modes | Description | | --- | --- | --- | | `mode` | all | `providerSearch` (default), `providerByNpi`, `locationSearch`, `organizationSearch`, `insuranceSearch`, `tinSearch`, `specialtySearch`, `procedureSearch`, `priceSearch`, `carrierSearch` or `costEstimate` | | `specialty` | provider search | Plain words, such as `cardiology` or `gastroenterologist` | | `name` | provider, location, organization, TIN search | Fuzzy name match | | `providerTypes` | provider, specialty search | Such as `Doctor`, `Nursing`, `Dental Providers` | | `gender`, `language`, `minRating`, `minAge`, `maxAge` | provider search | Provider filters | | `acceptingNewPatients` | provider search | Keep providers likely accepting new patients | | `procedure`, `condition` | provider search | Fuzzy matched to one H1 procedure or condition | | `address`, `latLng`, `distance` | provider, location, organization, price search | Center and radius in miles | | `state` | provider, insurance search | Two letter state code | | `insuranceCarrierName`, `insuranceIds` | provider, location search | In-network filters (carrier name on insurance search too) | | `organizationIds`, `healthSystem`, `minLocationConfidence` | provider, location search | Organization and confidence filters | | `npis`, `maxInsurances` | provider by NPI | Up to 500 NPIs a run | | `locationTypes`, `tier` | location search | Location type and quality tier 1 to 3 | | `searchText` | insurance, TIN, specialty, procedure search | Free text | | `planType`, `insuranceCategory`, `partialCodes` | insurance search | Such as `PPO`, `Medicare Advantage`, `H9572` | | `legalName`, `tinIds` | TIN search | Billing entity filters | | `procedureCode`, `procedureCodeScheme`, `careClusterCode`, `carrierId`, `carrierName` | price search (and procedure search, carriers) | Such as `27447`, `CPT`, `JOINT_REPLACEMENT`, `78110` | | `procedureIds`, `memberZip`, `estimateType`, `planId` | cost estimate | Procedure UUIDs, ZIP, `claims` or `price_transparency` | | `maxResults` | all | Row ceiling for the run (default 100) | | `requestsPerMinute` | all | Pacing, default 60 | | `apiKey` | all | Your H1 API key (or the DATA_API_KEY secret) | Example: in-network Aetna cardiologists within 10 miles of Manhattan who are accepting new patients. ```json { "mode": "providerSearch", "specialty": "cardiology", "address": "New York, NY", "distance": 10, "insuranceCarrierName": "Aetna", "acceptingNewPatients": true, "maxResults": 200 } ``` Example: negotiated prices for a total knee replacement near ZIP 10001. ```json { "mode": "priceSearch", "address": "10001", "distance": 25, "procedureCode": "27447", "carrierId": "78110" } ``` ### Example output An illustrative provider search row, shaped like the documented response (values are an example, not real data). The full H1 provider object is kept under `record`. ```json { "mode": "providerSearch", "modeLabel": "Provider search", "recordType": "provider", "query": "specialty=cardiology address=New York, NY distance=10", "id": "3530835", "npi": "1234567890", "name": "Jane J Doe", "firstName": "Jane", "middleName": "J", "lastName": "Doe", "gender": "f", "age": 48, "degrees": ["MD"], "providerTypes": ["Doctor"], "specialties": ["Cardiology"], "primarySpecialties": ["Cardiology"], "languages": ["english"], "ratingsAvg": 9.1, "ratingsCount": 57, "address": "123 Main St, New York, NY 10001", "city": "New York", "state": "NY", "zip": "10001", "latitude": 40.7506, "longitude": -73.9971, "phone": "2125550100", "locationCount": 2, "distanceMiles": 0.4, "acceptingNewPatients": true, "organizations": ["Acme Health"], "totalInsurances": 312, "found": true, "retrievedAt": "2026-10-20T12:00:00.000Z", "note": null, "record": { "npi": "1234567890", "first_name": "Jane", "locations": ["..."] } } ``` A negotiated price row carries `locationName` as `name`, `carrierId`, `carrierName`, `procedureCode`, `procedureCodeScheme`, `procedureDescription`, `careClusterCode`, `negotiatedType`, `negotiationArrangement`, `priceMin`, `priceMedian`, `priceAvg` and `priceMax`. A cost estimate row carries `costMin`, `costMedian` and `costMax`. ### FAQ #### What is the H1 (Ribbon Health) API? Ribbon Health built a healthcare provider directory API covering US providers, practice locations, insurance networks, cost and quality and price transparency data; H1 acquired it and now runs it as the H1 API on api.ribbonhealth.com, documented at ribbon.readme.io. It is authenticated with a Bearer API key issued to H1 customers. #### Do I need my own H1 API key? Yes. This is a bring-your-own-key actor: it calls H1 with your key, under your contract and terms. A missing or rejected key, or a module your contract does not include, ends the run cleanly with a status message that explains what to change, and nothing is charged. #### How do I look up a doctor by NPI? Choose Provider by NPI and add one 10 digit NPI per line. Each NPI returns the full H1 profile, including practice locations, phone numbers, specialties, languages, education, licenses and insurance network summary. An NPI H1 does not know becomes a free row with a note. #### How do I find in-network providers for a health plan? Run Insurance plan search with a carrier name or search text to get plan UUIDs, then run Provider search with those UUIDs in Insurance plan UUIDs, plus a specialty and an address. For a looser match, Insurance carrier name finds providers taking at least one plan from that carrier. #### What price transparency data does it return? Negotiated price search reads H1 Price Transparency v2: payer-filed negotiated rates per facility or practice location for a procedure code or care cluster near an address, with minimum, median, average and maximum per carrier, sorted cheapest first. Use the carriers mode to find carrier IDs. Price transparency is a separate H1 module. #### How accurate are the provider addresses? Each H1 location carries a confidence score from 0 to 5 for whether the provider practices there. Set Minimum location confidence to 3 or 4 to keep the most reliable addresses; H1 then caps a provider search at 1000 records. #### How many API requests does a run use? One per NPI, and one per page of 25 records (50 for price search, 100 for carriers) in the searches. Maximum results stops paging early, and the run log reports the exact request count. #### What do I pay? Pay per result: 0.015 USD per provider profile, 0.01 USD per negotiated price or cost estimate, and 0.005 USD per location, organization, insurance plan, TIN, specialty, procedure or carrier. Refused and empty lookups are never charged. Your H1 contract is billed separately by H1. ### Pricing | Event | Price | Charged for | | --- | --- | --- | | `provider-profile` | 0.015 USD | Each provider from provider search or provider by NPI | | `price-record` | 0.01 USD | Each negotiated price or procedure cost estimate | | `directory-record` | 0.005 USD | Each location, organization, insurance plan, TIN, specialty, procedure or carrier | ### Keyword map Healthcare provider data API, NPI lookup, NPI search, doctor search API, provider directory API, in-network provider search, insurance network data, health plan network, provider data enrichment, Ribbon Health API, H1 API, healthcare price transparency API, negotiated rates, CPT price lookup, procedure cost estimate, hospital and facility search, health system data, TIN lookup, provider specialty taxonomy, care navigation, network adequacy. ### Terms and data use H1 publishes no public API licence or data use terms; access to the API is governed by your customer agreement with H1. The H1 website Terms of Use (last revised April 11, 2021) apply to authorized users alongside that agreement, and say that content on H1's sites may not be copied, reproduced, distributed, transmitted or republished for commercial use without H1's prior written consent. They set no cache or retention time limit. Run this actor with your own key, keep the results for the uses your H1 agreement allows, and do not publish or resell them without written permission from H1. Some data, such as provider emails, dates of birth, panel demographics and cost and quality scores, are premium fields that may not be on your contract. This actor is not affiliated with or endorsed by H1 or Ribbon Health. # Actor input Schema ## `mode` (type: `string`): Provider search finds doctors and other clinicians by specialty, location, insurance, language, gender and more. Provider by NPI reads the full profile of each NPI. Location search finds hospitals, clinics, imaging, ambulatory and urgent care sites. Organization search finds health systems. Insurance plan, TIN, specialty and procedure search read H1 reference data and give the UUIDs other filters take. Negotiated price search returns payer-filed price transparency rates by facility. Carriers lists the carrier IDs price search takes. Procedure cost estimate gives the minimum, median and maximum cost near a ZIP code. Some modules are not on every H1 contract. ## `specialty` (type: `string`): Provider search only. A specialty in plain words, matched by H1 to the closest specialty, typos and colloquial names included, such as cardiology, gastroenterologist or stomach doc. ## `name` (type: `string`): Provider, location, organization and TIN search. A full, first, last or partial name, fuzzy matched against the provider, location, organization or billing entity name. ## `providerTypes` (type: `array`): Provider search, and Specialty search (one type). Higher level groupings of specialties, such as Doctor, Nursing, Dental Providers, Optometry or Chiropractic Providers. ## `gender` (type: `string`): Provider search only. ## `language` (type: `string`): Provider search only. Fuzzy matched, such as English: providers who, or whose office staff, speak it. ## `acceptingNewPatients` (type: `boolean`): Provider search only. Keeps providers H1 marks as likely accepting new patients at a location. ## `minRating` (type: `integer`): Provider search only. Average patient satisfaction rating out of 10. ## `minAge` (type: `integer`): Provider search only. ## `maxAge` (type: `integer`): Provider search only. ## `procedure` (type: `string`): Provider search only. A procedure in plain words, such as MRI, thoracic spine, fuzzy matched to one H1 procedure. ## `condition` (type: `string`): Provider search only. A condition such as depression, fuzzy matched to one H1 condition. A premium focus area field on some contracts. ## `address` (type: `string`): Provider, location, organization and negotiated price search. An address, city or ZIP code, geocoded by H1, such as New York, NY or 10001. Required for negotiated price search unless coordinates are given. ## `latLng` (type: `string`): Instead of an address: latitude,longitude such as 40.7506,-73.9971. ## `distance` (type: `integer`): Search radius around the address or coordinates. H1 suggests under 50 miles when filtering by insurance or location confidence; negotiated price search defaults to 25. ## `state` (type: `string`): Provider search and Insurance plan search. Two letter state code such as NY. On provider search it overrides the address and coordinates. ## `insuranceCarrierName` (type: `string`): Provider, location and insurance plan search. A carrier name as H1 spells it on its insurance objects, such as Aetna. Finds providers or locations taking at least one plan from that carrier. ## `insuranceIds` (type: `array`): Provider and location search. In-network filter: plan UUIDs from Insurance plan search, one per line. ## `organizationIds` (type: `array`): Provider and location search. Organization UUIDs from Organization search, one per line. ## `healthSystem` (type: `string`): Provider and location search. Prefix of the ultimate parent organization name, such as Acme Health. ## `minLocationConfidence` (type: `integer`): Provider and location search. H1 confidence score (0 to 5) that a provider practices at, or a location is, where listed. 3 or 4 keeps the most reliable addresses. Caps a provider search at 1000 records. ## `npis` (type: `array`): Provider by NPI only. One 10 digit National Provider Identifier per line, up to 500 a run. Each NPI is one request. ## `maxInsurances` (type: `integer`): Provider by NPI only. Returns at most this many accepted insurances per location, to keep profiles small. ## `locationTypes` (type: `array`): Location search only. H1 location types, such as Urgent Care, one per line. H1 sorts locations into some 30 types across hospitals, clinics, urgent care, ambulatory and imaging centers. ## `tier` (type: `string`): Location search only. Quality tier derived from the linked organization. ## `searchText` (type: `string`): Insurance plan, TIN, specialty and procedure search. Free text fuzzy matched by H1, such as Aetna for plans or cardiology for specialties. ## `planType` (type: `string`): Insurance plan search only. Exact plan type as H1 spells it, such as PPO or HMO. ## `insuranceCategory` (type: `string`): Insurance plan search only. Exact category as H1 spells it, such as Medicare Advantage. ## `partialCodes` (type: `string`): Insurance plan search only. A Medicare Advantage contract ID such as H9572, or the first 10 digits of an exchange plan HIOS ID. ## `legalName` (type: `string`): TIN search only. Fuzzy matched against the legal name of the billing entity. ## `tinIds` (type: `array`): TIN search only. 9 digit taxpayer identification numbers, one per line. H1 takes no other TIN filter with these. ## `procedureCode` (type: `string`): Procedure search and negotiated price search. A billing code such as CPT 27447 (total knee replacement). ## `procedureCodeScheme` (type: `string`): Negotiated price search only. Coding system, such as CPT or HCPCS. ## `careClusterCode` (type: `string`): Negotiated price search only. An H1 care cluster business code such as JOINT_REPLACEMENT. ## `carrierId` (type: `string`): Negotiated price search and carriers. The v2 carrier business ID from the carriers mode, such as 78110. Not the same as an insurance plan UUID. ## `carrierName` (type: `string`): Negotiated price search and carriers. Carrier display name, such as Aetna. Prefer the carrier ID for price search. ## `procedureIds` (type: `array`): Procedure cost estimate only. Procedure UUIDs from Procedure search; the estimate covers them combined. ## `memberZip` (type: `string`): Procedure cost estimate only. The 5 digit ZIP code of the patient. ## `estimateType` (type: `string`): Procedure cost estimate only. Price transparency estimates need the insurance plan UUID. ## `planId` (type: `string`): Procedure cost estimate with price transparency data only. The plan UUID from Insurance plan search. ## `maxResults` (type: `integer`): The most rows this run returns and charges for. Searches stop paging once this many rows are in, so no request is spent on rows that would be cut. ## `requestsPerMinute` (type: `integer`): Pacing. A rate limit answer is waited out and retried; a used up allowance ends the run. ## `apiKey` (type: `string`): Your own H1 API key (formerly a Ribbon Health API key), issued by H1. Sent only to api.ribbonhealth.com as a Bearer token, never logged. Stored as a secret. You can instead set the DATA_API_KEY environment secret. ## Actor input object example ```json { "mode": "providerSearch", "specialty": "cardiology", "gender": "any", "acceptingNewPatients": false, "address": "New York, NY", "distance": 10, "tier": "any", "estimateType": "claims", "maxResults": 100, "requestsPerMinute": 60 } ``` # Actor output Schema ## `records` (type: `string`): One row per record returned for the chosen mode. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "specialty": "cardiology", "address": "New York, NY", "distance": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("nabeelbaghoor/healthcare-provider-data-api").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "specialty": "cardiology", "address": "New York, NY", "distance": 10, } # Run the Actor and wait for it to finish run = client.actor("nabeelbaghoor/healthcare-provider-data-api").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "specialty": "cardiology", "address": "New York, NY", "distance": 10 }' | apify call nabeelbaghoor/healthcare-provider-data-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/healthcare-provider-data-api" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/eLq1Z3DpW28622DPj/builds/Fw8KOE1ANckgdDe8G/openapi.json