Skip to main content
POST
Returns US health care organizations (clinics, hospitals, pharmacies and suppliers) from the national provider register of the US Centers for Medicare & Medicaid Services, by 10-digit NPI or by name and state: names, status, specialties, license details, addresses and the authorized official. Registration is not a license check or proof of current practice at the address.

Authentication

Requires x402 payment in the payment-signature header.

Request Body

string
The organisation provider number. Give this, or organization_name and state, never both. A health provider number is exactly 10 digits.
string
Organisation name prefix. Needs state; a trailing * is appended when absent. 2 to 100 characters. Give at least two characters before an optional trailing *.
string
US state code. Needs organization_name. A state is two capital letters, such as MN.
string
A city, to narrow a name search. An optional trailing * needs at least two preceding characters. 1 to 100 characters.
integer
Most providers to return. From 1 to 20. Defaults to 5.

Response (200 OK)

Top-level envelope: success (boolean) and data (object). All fields below are nested under data.
string
Durable job ID for audit and lookup
string
Job status: completed
string
Always company_health_provider
object
The answer, described under Result below
object
Where the answer came from and when
boolean
true when the answer was served from OneShot’s store of earlier lookups (or its own copy of a public dataset), false when the source was asked for this call
string
When the record was obtained from its source, as an ISO 8601 UTC time; equals evidence.retrieved_at
string
The public body the data comes from. Always US Centers for Medicare & Medicaid Services.
string
public when the data comes from a public body, commercial otherwise
string
When the lookup was made, as an ISO 8601 UTC time
string | null
When the source says the fact was last updated, or null when the source gives no date

Result

Nested under data.result.
number
Number of providers returned.
object[]
Providers.
string
The 10-digit provider number.
string | null
Organization name. null when the source gives no value.
string[]
Other names.
boolean
True when registered as an organisational subpart.
boolean
True when the registration is active.
string | null
Date the 10-digit number was issued, YYYY-MM-DD. null when the source gives no value.
string | null
Date the registry last updated the record, YYYY-MM-DD. null when the source gives no value.
object[]
Specialties.
string | null
Taxonomy code. null when the source gives no value.
string | null
Description. null when the source gives no value.
boolean
Primary.
string | null
License state. null when the source gives no value.
string | null
License number. null when the source gives no value.
object | null
Where they practise, as registered. null when the source gives no value.
string | null
Street. null when the source gives no value.
string | null
City. null when the source gives no value.
string | null
State. null when the source gives no value.
string | null
Postal code. null when the source gives no value.
string | null
Phone. null when the source gives no value.
object | null
Where they receive mail, as registered. null when the source gives no value.
string | null
Street. null when the source gives no value.
string | null
City. null when the source gives no value.
string | null
State. null when the source gives no value.
string | null
Postal code. null when the source gives no value.
string | null
Phone. null when the source gives no value.
object
Authorized official.
string | null
Name. null when the source gives no value.
string | null
Title. null when the source gives no value.
See Pricing for this tool’s price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers 200.

Notes

  • Give a 10-digit NPI, or organization_name and state with an optional city, never both.
  • Names match a prefix: a trailing * is appended when absent, with at least two characters before it.
  • Returns registered names, active status, organizational subpart status, registration and update dates, specialties with primary flags and license details, practice and mailing addresses, and the authorized official name and title. The official telephone is omitted.
  • The registry refreshes daily; judge each record by last_updated_on.
  • Use person_health_provider for individual practitioners.
  • total is the number returned, at most limit; no match completes with providers: [].
  • Results return inline. The finished job stays available at /v1/requests/{request_id}