Skip to main content
POST
Look up the national registration of an individual US health care practitioner (a doctor, nurse, pharmacist, therapist and the like) by 10-digit provider number, or by last name and state with optional first name and city. Returns each match with credential, whether the registration is active, specialties with licence state and number, practice address and mailing address, and the date the registry last updated the record. Use it to check that a practitioner in a directory, claim or referral exists and which specialty they are registered under. A registration is not a licence check and not proof that they still practise at the address; judge freshness by last_updated_on. Individuals only: organisations are not covered. total is the number of providers returned, at most limit; no match is total: 0.

​
Authentication

Requires x402 payment in the payment-signature header.

​
Request Body

​
string
The 10-digit provider number. Give this, or a last name and state, never both. A health provider number is exactly 10 digits.
​
string
Last name of the practitioner. Needs state. 1 to 100 characters.
​
string
Two-letter US state code, such as TX. Needs last name. A state is two capital letters, such as TX.
​
string
First name of the practitioner, to narrow a name search. 1 to 100 characters.
​
string
A city, to narrow a name search. 1 to 100 characters.
​
integer
Most providers to return from a name search, 1 to 20. 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 person_health_provider
​
object
The answer, described under Result below
​
object
Where the answer came from and when
​
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
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
First name. null when the source gives no value.
​
string
Last name. null when the source gives no value.
​
string
Credential as registered, such as MD. null when the source gives no value.
​
boolean
True when the registration is active.
​
string
Date the 10-digit number was issued, YYYY-MM-DD. null when the source gives no value.
​
string
Date the registry last updated the record, YYYY-MM-DD. null when the source gives no value.
​
object[]
Specialties.
​
string
Taxonomy code. null when the source gives no value.
​
string
Description. null when the source gives no value.
​
boolean
Primary.
​
string
License state. null when the source gives no value.
​
string
License number. null when the source gives no value.
​
object
Where they practise, as registered. null when the source gives no value.
​
string
Street. null when the source gives no value.
​
string
City. null when the source gives no value.
​
string
State. null when the source gives no value.
​
string
Postal code. null when the source gives no value.
​
string
Phone. null when the source gives no value.
​
object
Where they receive mail, as registered. null when the source gives no value.
​
string
Street. null when the source gives no value.
​
string
City. null when the source gives no value.
​
string
State. null when the source gives no value.
​
string
Postal code. null when the source gives no value.
​
string
Phone. null when the source gives no value.
Price: $0.005 per lookup. See Pricing for every tool.

​
Notes

  • Results return inline. The finished job stays available at /v1/requests/{request_id}