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.

{
    "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.

{
    "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.

{
    "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.