Server definition
- Hash
- sha256:0dc46b240532d7ce8e112ece3bc395a8093492484d3f32cbca647e7a37d69cf5
- What it is
- What a remote MCP server returned when asked what it offers: 3 tools
The blob, as servednamed by its sha256
{
"instructions": "US healthcare provider directory over the live, keyless NPPES NPI Registry, plus a bundled NUCC taxonomy code set for offline specialty resolution. Public professional practice data only (name, practice address, specialty, credential, NPI) — no personal or home data, so only practice-location (LOCATION) addresses are kept for individual providers and their mailing address is withheld. Typical flow: npi_search_providers (resolve a name/specialty/place to candidate NPIs) → npi_get_provider (decode one or more NPIs to their provider records). Ground plain-language specialties with npi_lookup_taxonomy before searching. The registry never reports a true match total and one search reaches only its first 1200 matches by skip; npi_search_providers names the next page, and at that terminal window returns postal_code prefixes that continue the search.",
"tools": [
{
"description": "Fetch the NPPES record for one or more NPI numbers (up to 10 per call). Decodes an NPI from a claim, prescription, or another health data source into the provider's professional-practice profile: every taxonomy with its primary flag, license number and state; practice addresses with phone and fax (only LOCATION rows are kept for individual providers, so their mailing address is withheld; organizations also carry their mailing address); credential, sex, sole-proprietor flag; enumeration and last-updated dates; active/deactivated status; secondary identifiers (Medicaid, etc.); and FHIR/Direct endpoints. Each NPI must be 10 digits with a valid check digit (its last digit); an NPI failing the check digit lands in invalid and is never looked up. Reports partial success: valid NPIs with no registry record (deactivated or never enumerated) land in notFound, while NPIs whose lookup hit an upstream error (registry unavailable, timeout) land in errored — kept distinct from confirmed misses — rather than failing the whole call.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"npis": {
"anyOf": [
{
"description": "A 10-digit National Provider Identifier whose last digit is its check digit (Luhn over the number prefixed with 80840).",
"pattern": "^\\d{10}$",
"type": "string"
},
{
"description": "An array of up to 10 ten-digit NPIs.",
"items": {
"description": "A 10-digit National Provider Identifier whose last digit is its check digit (Luhn over the number prefixed with 80840).",
"pattern": "^\\d{10}$",
"type": "string"
},
"maxItems": 10,
"minItems": 1,
"type": "array"
}
],
"description": "A single 10-digit NPI, or an array of up to 10. Each must be exactly 10 digits; each is also checked against its NPI check digit before any API call, and one that fails is reported in invalid."
}
},
"required": [
"npis"
],
"type": "object"
},
"name": "npi_get_provider",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"found",
"notFound",
"errored",
"invalid",
"totalCount"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `none_found`: Every requested NPI with a valid check digit returned a confirmed no-record response — none failed with an upstream error (those surface as the underlying service/timeout error instead). `invalid_npi_format`: Every requested NPI failed the NPI check digit, so none was looked up. Other values are possible when a failure originates below the handler.",
"examples": [
"none_found",
"invalid_npi_format"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"errored": {
"description": "NPIs whose lookups failed with an upstream/transport error (service unavailable, timeout) — distinct from a confirmed miss in notFound. These are unresolved, not absent; retry them.",
"items": {
"additionalProperties": false,
"description": "A requested NPI whose lookup failed with an upstream error.",
"properties": {
"npi": {
"description": "The requested NPI whose lookup failed operationally.",
"type": "string"
},
"reason": {
"description": "The upstream failure reason (service unavailable, timeout, etc.).",
"type": "string"
}
},
"required": [
"npi",
"reason"
],
"type": "object"
},
"type": "array"
},
"found": {
"description": "Decoded records for NPIs that resolved.",
"items": {
"additionalProperties": false,
"description": "A decoded NPPES provider record — the registry's professional-practice data. Only LOCATION address rows are kept for individual providers.",
"properties": {
"addresses": {
"description": "Registry addresses. Only LOCATION (practice) rows are kept for individual providers — their mailing address is withheld; organizations carry both LOCATION and MAILING rows.",
"items": {
"additionalProperties": false,
"description": "A practice (LOCATION) address, or an organization mailing address.",
"properties": {
"addressType": {
"description": "Address type (DOM domestic or FOR foreign).",
"type": "string"
},
"city": {
"description": "City.",
"type": "string"
},
"countryCode": {
"description": "ISO country code.",
"type": "string"
},
"countryName": {
"description": "Country name.",
"type": "string"
},
"faxNumber": {
"description": "Fax number, when present.",
"type": "string"
},
"line1": {
"description": "Address line 1.",
"type": "string"
},
"line2": {
"description": "Address line 2.",
"type": "string"
},
"postalCode": {
"description": "Postal/ZIP code.",
"type": "string"
},
"purpose": {
"description": "Address purpose: LOCATION (practice) or MAILING. Only LOCATION rows are kept for individual providers; organizations also carry MAILING.",
"type": "string"
},
"state": {
"description": "State.",
"type": "string"
},
"telephoneNumber": {
"description": "Telephone number, when present.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"authorizedOfficial": {
"additionalProperties": false,
"description": "Authorized official block, for organizations.",
"properties": {
"credential": {
"description": "Authorized official credential.",
"type": "string"
},
"firstName": {
"description": "Authorized official first name.",
"type": "string"
},
"lastName": {
"description": "Authorized official last name.",
"type": "string"
},
"middleName": {
"description": "Authorized official middle name.",
"type": "string"
},
"namePrefix": {
"description": "Authorized official name prefix, when present.",
"type": "string"
},
"nameSuffix": {
"description": "Authorized official name suffix, when present.",
"type": "string"
},
"telephoneNumber": {
"description": "Authorized official telephone number.",
"type": "string"
},
"title": {
"description": "Authorized official title or position.",
"type": "string"
}
},
"type": "object"
},
"certificationDate": {
"description": "Certification date, when present.",
"type": "string"
},
"createdEpoch": {
"description": "Record creation timestamp, epoch milliseconds, when present.",
"type": "number"
},
"credential": {
"description": "Credential (e.g. \"MD\"), when present.",
"type": "string"
},
"endpoints": {
"description": "FHIR / Direct endpoints, when present.",
"items": {
"additionalProperties": false,
"description": "A FHIR or Direct messaging endpoint with its routing address and context.",
"properties": {
"addressType": {
"description": "Endpoint address type (DOM/FOR), when present.",
"type": "string"
},
"affiliation": {
"description": "Whether the endpoint is affiliated with an organization (Y/N), when present.",
"type": "string"
},
"affiliationName": {
"description": "Name of the affiliated organization, when present.",
"type": "string"
},
"city": {
"description": "Endpoint city, when present.",
"type": "string"
},
"contentOtherDescription": {
"description": "The content the endpoint carries when the content type is OTHER (e.g. \"C-CDA\"), when present.",
"type": "string"
},
"contentType": {
"description": "Endpoint content type code, when present.",
"type": "string"
},
"contentTypeDescription": {
"description": "Endpoint content type description, when present.",
"type": "string"
},
"countryCode": {
"description": "Endpoint ISO country code, when present.",
"type": "string"
},
"countryName": {
"description": "Endpoint country name, when present.",
"type": "string"
},
"endpoint": {
"description": "The endpoint URI/address.",
"type": "string"
},
"endpointDescription": {
"description": "Free-text description of the endpoint (e.g. \"Carequality\"), when present.",
"type": "string"
},
"endpointType": {
"description": "Endpoint type code (e.g. \"DIRECT\", \"FHIR\").",
"type": "string"
},
"endpointTypeDescription": {
"description": "Endpoint type description.",
"type": "string"
},
"line1": {
"description": "Endpoint address line 1, when present.",
"type": "string"
},
"line2": {
"description": "Endpoint address line 2, when present.",
"type": "string"
},
"postalCode": {
"description": "Endpoint postal/ZIP code, when present.",
"type": "string"
},
"state": {
"description": "Endpoint state, when present.",
"type": "string"
},
"use": {
"description": "Endpoint use code (e.g. \"HIE\"), when present.",
"type": "string"
},
"useDescription": {
"description": "Endpoint use description, when present.",
"type": "string"
},
"useOtherDescription": {
"description": "What the endpoint is used for when the use code is OTHER, when present.",
"type": "string"
}
},
"required": [
"endpoint"
],
"type": "object"
},
"type": "array"
},
"enumerationDate": {
"description": "Date the NPI was enumerated.",
"type": "string"
},
"firstName": {
"description": "First name, for individuals.",
"type": "string"
},
"identifiers": {
"description": "Secondary identifiers (Medicaid, etc.), when present.",
"items": {
"additionalProperties": false,
"description": "A secondary identifier (Medicaid, etc.).",
"properties": {
"code": {
"description": "Identifier type code.",
"type": "string"
},
"description": {
"description": "Identifier type description (e.g. \"MEDICAID\").",
"type": "string"
},
"identifier": {
"description": "The secondary identifier value.",
"type": "string"
},
"issuer": {
"description": "Issuing organization, when present.",
"type": "string"
},
"state": {
"description": "Associated state, when present.",
"type": "string"
}
},
"required": [
"identifier"
],
"type": "object"
},
"type": "array"
},
"lastName": {
"description": "Last name, for individuals.",
"type": "string"
},
"lastUpdated": {
"description": "Date the record was last updated.",
"type": "string"
},
"lastUpdatedEpoch": {
"description": "Record last-update timestamp, epoch milliseconds, when present.",
"type": "number"
},
"middleName": {
"description": "Middle name, when present.",
"type": "string"
},
"name": {
"description": "Assembled \"First Last\" or organization name.",
"type": "string"
},
"namePrefix": {
"description": "Name prefix (e.g. \"Dr.\"), when present.",
"type": "string"
},
"nameSuffix": {
"description": "Name suffix (e.g. \"Jr.\"), when present.",
"type": "string"
},
"npi": {
"description": "10-digit National Provider Identifier.",
"type": "string"
},
"organizationName": {
"description": "Organization legal name, for organizations.",
"type": "string"
},
"organizationalSubpart": {
"description": "Organizational subpart flag, for organizations.",
"type": "string"
},
"otherNames": {
"description": "Former / alternate names, when present.",
"items": {
"additionalProperties": false,
"description": "A former or alternate name.",
"properties": {
"credential": {
"description": "Credential, when present.",
"type": "string"
},
"firstName": {
"description": "First name, for individuals.",
"type": "string"
},
"lastName": {
"description": "Last name, for individuals.",
"type": "string"
},
"middleName": {
"description": "Middle name, for individuals, when present.",
"type": "string"
},
"organizationName": {
"description": "Organization name, for organizations.",
"type": "string"
},
"prefix": {
"description": "Name prefix, when present.",
"type": "string"
},
"suffix": {
"description": "Name suffix, when present.",
"type": "string"
},
"type": {
"description": "Other-name type (former name, DBA, etc.).",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"practiceLocations": {
"description": "Additional practice locations, when present.",
"items": {
"additionalProperties": false,
"description": "A practice (LOCATION) address, or an organization mailing address.",
"properties": {
"addressType": {
"description": "Address type (DOM domestic or FOR foreign).",
"type": "string"
},
"city": {
"description": "City.",
"type": "string"
},
"countryCode": {
"description": "ISO country code.",
"type": "string"
},
"countryName": {
"description": "Country name.",
"type": "string"
},
"faxNumber": {
"description": "Fax number, when present.",
"type": "string"
},
"line1": {
"description": "Address line 1.",
"type": "string"
},
"line2": {
"description": "Address line 2.",
"type": "string"
},
"postalCode": {
"description": "Postal/ZIP code.",
"type": "string"
},
"purpose": {
"description": "Address purpose: LOCATION (practice) or MAILING. Only LOCATION rows are kept for individual providers; organizations also carry MAILING.",
"type": "string"
},
"state": {
"description": "State.",
"type": "string"
},
"telephoneNumber": {
"description": "Telephone number, when present.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"sex": {
"description": "Sex code, for individuals, when present.",
"type": "string"
},
"soleProprietor": {
"description": "Sole-proprietor flag (YES/NO), when present.",
"type": "string"
},
"status": {
"description": "Registry status — never treat a deactivated NPI as current.",
"enum": [
"active",
"deactivated"
],
"type": "string"
},
"taxonomies": {
"description": "All taxonomies (specialties) on the record.",
"items": {
"additionalProperties": false,
"description": "A taxonomy (specialty) on the record.",
"properties": {
"code": {
"description": "Taxonomy code.",
"type": "string"
},
"description": {
"description": "Taxonomy description.",
"type": "string"
},
"license": {
"description": "License number for this taxonomy, when present.",
"type": "string"
},
"primary": {
"description": "Whether this is the provider's primary taxonomy.",
"type": "boolean"
},
"state": {
"description": "License state for this taxonomy, when present.",
"type": "string"
},
"taxonomyGroup": {
"description": "Taxonomy group, when present.",
"type": "string"
}
},
"required": [
"code",
"primary"
],
"type": "object"
},
"type": "array"
},
"type": {
"description": "Enumeration type (NPI-1 vs NPI-2).",
"enum": [
"individual",
"organization"
],
"type": "string"
}
},
"required": [
"npi",
"type",
"status",
"name",
"taxonomies",
"addresses",
"practiceLocations",
"identifiers",
"otherNames",
"endpoints"
],
"type": "object"
},
"type": "array"
},
"invalid": {
"description": "NPIs that failed the NPI check digit — not valid NPIs, usually a typo. They were never looked up, so they are neither confirmed misses nor upstream failures.",
"items": {
"additionalProperties": false,
"description": "A requested NPI that failed the NPI check digit.",
"properties": {
"npi": {
"description": "The requested NPI that failed the check digit.",
"type": "string"
},
"reason": {
"description": "Why the NPI was rejected.",
"type": "string"
}
},
"required": [
"npi",
"reason"
],
"type": "object"
},
"type": "array"
},
"notFound": {
"description": "NPIs with a valid check digit that returned no record (deactivated or never enumerated). A confirmed absence, not a failure.",
"items": {
"additionalProperties": false,
"description": "A requested NPI that returned no record.",
"properties": {
"npi": {
"description": "The requested NPI with no record.",
"type": "string"
},
"reason": {
"description": "Why it returned nothing (e.g. no registry record).",
"type": "string"
}
},
"required": [
"npi",
"reason"
],
"type": "object"
},
"type": "array"
},
"notice": {
"description": "Guidance when some NPIs failed the check digit, returned no record, or hit an upstream error.",
"type": "string"
},
"totalCount": {
"description": "Number of provider records that resolved from the requested NPIs.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "Resolve and browse the NUCC Healthcare Provider Taxonomy — the specialty code set NPPES uses — fully offline (bundled). Mode `resolve` turns a plain-language specialty (e.g. \"cardiologist\", \"heart doctor\") into matching active taxonomy entries, excluding codes NUCC marks inactive; mode `get` returns the full entry for an exact code, including NUCC's Notes; mode `browse` walks the hierarchy (grouping → classification → specialization), optionally filtered by grouping and by NPI section (Individual/NPI-1 vs Non-Individual/NPI-2). Every entry carries its status, and an inactive code names its replacement when NUCC gives one; `get` and `browse` still return inactive codes. A resolved entry's specialization, or its classification when specialization is absent, maps directly to npi_search_providers.taxonomy_description.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"oneOf": [
{
"additionalProperties": false,
"properties": {
"limit": {
"default": 20,
"description": "Maximum matching entries to return (1–50).",
"maximum": 50,
"minimum": 1,
"type": "integer"
},
"mode": {
"const": "resolve",
"description": "Resolve a plain-language specialty to taxonomy codes.",
"type": "string"
},
"query": {
"description": "The plain-language specialty term to resolve, e.g. \"pediatric cardiologist\".",
"minLength": 1,
"type": "string"
},
"skip": {
"default": 0,
"description": "Entries to skip before the page (0–1000). Keep the same query and limit, then raise skip by limit each call.",
"maximum": 1000,
"minimum": 0,
"type": "integer"
}
},
"required": [
"mode",
"query"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"code": {
"description": "The exact NUCC taxonomy code, e.g. \"207RC0000X\".",
"minLength": 1,
"type": "string"
},
"mode": {
"const": "get",
"description": "Fetch one exact taxonomy entry by code.",
"type": "string"
}
},
"required": [
"mode",
"code"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"grouping": {
"description": "Filter to a top-level grouping by case-insensitive substring, e.g. \"physicians\".",
"type": "string"
},
"limit": {
"default": 20,
"description": "Maximum entries to return (1–50).",
"maximum": 50,
"minimum": 1,
"type": "integer"
},
"mode": {
"const": "browse",
"description": "Browse the taxonomy hierarchy.",
"type": "string"
},
"section": {
"description": "Filter by NPI section: Individual (NPI-1) or Non-Individual (NPI-2).",
"enum": [
"Individual",
"Non-Individual"
],
"type": "string"
},
"skip": {
"default": 0,
"description": "Entries to skip before the page (0–1000). Keep the same filters and limit, then raise skip by limit each call.",
"maximum": 1000,
"minimum": 0,
"type": "integer"
}
},
"required": [
"mode"
],
"type": "object"
}
],
"type": "object"
},
"name": "npi_lookup_taxonomy",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"matches"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The limit that was applied.",
"type": "number"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `no_match`: A get code matched no taxonomy entry, a resolve query matched no active one (the message names any inactive codes it matched), or a resolve query was made only of generic words (\"doctor\", \"M.D.\", \"specialist\") that name no specialty. `missing_argument`: The required query or code was present but blank after trimming. Other values are possible when a failure originates below the handler.",
"examples": [
"no_match",
"missing_argument"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"matches": {
"description": "Matching taxonomy entries. For mode \"get\" this is the single requested entry; for \"resolve\"/\"browse\" it is the ranked/sorted matches up to limit.",
"items": {
"additionalProperties": false,
"description": "A single NUCC taxonomy entry.",
"properties": {
"classification": {
"description": "Classification within the grouping, e.g. \"Internal Medicine\".",
"type": "string"
},
"code": {
"description": "NUCC taxonomy code, e.g. \"207RC0000X\".",
"type": "string"
},
"definition": {
"description": "Scope note / definition. Absent for a handful of codes.",
"type": "string"
},
"displayName": {
"description": "Human-readable display name, e.g. \"Cardiovascular Disease Physician\".",
"type": "string"
},
"grouping": {
"description": "Top-level grouping, e.g. \"Allopathic & Osteopathic Physicians\".",
"type": "string"
},
"notes": {
"description": "NUCC Notes: sources, revision history, and status remarks. Returned by mode \"get\" only, when NUCC records a note.",
"type": "string"
},
"replacedBy": {
"description": "For an inactive code, the active replacement code NUCC names, when it names one.",
"type": "string"
},
"section": {
"description": "NPI enumeration scope: Individual (NPI-1) or Non-Individual (NPI-2).",
"enum": [
"Individual",
"Non-Individual"
],
"type": "string"
},
"specialization": {
"description": "Specialization within the classification, e.g. \"Cardiovascular Disease\". Absent for top-level classification codes.",
"type": "string"
},
"status": {
"description": "NUCC status. Inactive codes are no longer maintained: mode \"resolve\" excludes them, while \"get\" and \"browse\" return them.",
"enum": [
"active",
"inactive"
],
"type": "string"
}
},
"required": [
"code",
"grouping",
"classification",
"displayName",
"section",
"status"
],
"type": "object"
},
"type": "array"
},
"notice": {
"description": "Guidance — how to page a truncated result with skip, or how to broaden when nothing matched.",
"type": "string"
},
"shown": {
"description": "Number of entries returned.",
"type": "number"
},
"truncated": {
"description": "True when the list was capped at `limit` (more entries may match).",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Search the NPPES NPI registry for individual practitioners and healthcare organizations by name, organization name, location, provider type, and specialty. Plain-language specialty terms (e.g. \"cardiologist\", \"pediatric cardiologist\") resolve through the bundled NUCC taxonomy; the top match's specialization or classification becomes taxonomy_description, and all resolved candidates are returned in metadata. Location belongs in the dedicated city/state/postal_code inputs, not inside specialty. Each provider row includes the NPI, name, primary specialty, city/state/ZIP, type, and active/deactivated status; the NPI is the input for npi_get_provider when the full record is needed. At least one search criterion is required, and the registry rejects state-only searches. When city/state/postal_code are given, only practice addresses are searched, never mailing addresses: a provider is returned only when its primary practice location or one of its other practice locations matches all of them. A provider kept on another practice location names it in matchedLocation. Name searches also match former and other names, sorted by current name; such a row names the matching name in matchedOtherName. The registry never reports a true match total, and one search reaches only its first 1200 matches: a full page names the next in nextPage, and the terminal window (skip 1000, limit 200) returns continuationPostalCodes, postal_code prefixes that continue the search.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"city": {
"description": "Practice-location city, case-insensitive. A trailing \"*\" after at least 2 characters matches every city starting with them (e.g. \"SAN F*\").",
"pattern": "^[^*]*$|^[^*]{2,}\\*$",
"type": "string"
},
"first_name": {
"description": "Individual first name. Trailing wildcard \"*\" allowed with at least 2 leading characters.",
"type": "string"
},
"last_name": {
"description": "Individual last name. Trailing wildcard \"*\" allowed with at least 2 leading characters.",
"type": "string"
},
"limit": {
"default": 10,
"description": "Maximum providers to return (1–200; the registry caps at 200).",
"maximum": 200,
"minimum": 1,
"type": "integer"
},
"name_search": {
"description": "One person's name. The first token becomes first_name and the last token becomes last_name; use first_name/last_name when middle names or multi-part surnames matter.",
"type": "string"
},
"organization_name": {
"description": "Organization name (implies provider_type organization; cannot be combined with first_name, last_name, or name_search). Trailing wildcard \"*\" allowed with at least 2 leading characters.",
"type": "string"
},
"postal_code": {
"description": "Practice-location ZIP code: 5 digits (also matching the ZIP+4 codes that extend it), 9 digits, or a 2–9 digit prefix with one trailing \"*\" (e.g. \"98*\", \"981*\"). A ZIP+4 prefix (6+ digits) never matches a practice address recorded with only a 5-digit ZIP.",
"pattern": "^[^*]*$|^\\d{2,9}\\*$",
"type": "string"
},
"provider_type": {
"description": "Restrict to individuals (NPI-1) or organizations (NPI-2). Omit to search both; when set, it must match the name fields (\"individual\" for first_name/last_name/name_search, \"organization\" for organization_name).",
"enum": [
"individual",
"organization"
],
"type": "string"
},
"skip": {
"default": 0,
"description": "Results to skip for pagination (0–1000). A full page names the next in nextPage.",
"maximum": 1000,
"minimum": 0,
"type": "integer"
},
"specialty": {
"description": "Plain-language specialty (e.g. \"pediatric cardiologist\"), resolved through the bundled NUCC taxonomy to exact descriptions before searching. Codes NUCC marks inactive are never resolved. The matched taxonomy is echoed in the result. Mutually exclusive with taxonomy_description.",
"type": "string"
},
"state": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "2-letter state code (e.g. \"WA\").",
"pattern": "^[A-Z]{2}$",
"type": "string"
}
],
"description": "2-letter state code (e.g. \"WA\"). The registry rejects state-only searches, so another criterion is required. A blank value is treated as omitted."
},
"taxonomy_description": {
"description": "Exact NUCC taxonomy description for direct passthrough — use when the taxonomy description is already known. Mutually exclusive with specialty.",
"type": "string"
}
},
"type": "object"
},
"name": "npi_search_providers",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"providers"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"appliedTaxonomyDescription": {
"description": "The exact NUCC specialization or classification used as the specialty filter.",
"type": "string"
},
"cap": {
"description": "The limit that was applied.",
"type": "number"
},
"continuationPostalCodes": {
"description": "Present only at the terminal window (a full page at skip 1000, limit 200): postal_code prefixes that continue the same search, each re-run from skip 0 with the same arguments — the notice gives the full procedure. Empty when no postal split remains (postal_code is already a 5-digit ZIP, a full ZIP+4, or not a numeric ZIP prefix).",
"items": {
"description": "A trailing-\"*\" postal_code prefix.",
"type": "string"
},
"type": "array"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `no_search_criteria`: No effective search criterion was provided. `conflicting_specialty`: Both specialty and taxonomy_description were supplied. `mixed_provider_criteria`: Individual criteria (first_name, last_name, name_search) were combined with organization criteria (organization_name), directly or through provider_type. `unresolved_specialty`: The specialty term matched no active NUCC taxonomy (the message names any inactive codes it matched), or was made only of generic words (\"doctor\", \"M.D.\", \"specialist\") that name no specialty. `invalid_search_field`: The registry returned a field error (e.g. wildcard under 2 characters, bad provider type). Other values are possible when a failure originates below the handler.",
"examples": [
"no_search_criteria",
"conflicting_specialty",
"mixed_provider_criteria",
"unresolved_specialty",
"invalid_search_field"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"nextPage": {
"additionalProperties": false,
"description": "The next page: re-run the same arguments with this skip and limit. Present after a full page while rows remain reachable. When skip + limit passes 1000 it is skip 1000, limit 200, whose leading rows repeat rows already returned (the notice says how many) — dedupe by NPI.",
"properties": {
"limit": {
"description": "The limit to send for the next page.",
"type": "number"
},
"skip": {
"description": "The skip to send for the next page.",
"type": "number"
}
},
"required": [
"skip",
"limit"
],
"type": "object"
},
"notice": {
"description": "Guidance — the page-size-not-total caveat, the next page or terminal-window continuation procedure, other-name and location-filter counts, or how to broaden an empty result.",
"type": "string"
},
"providers": {
"description": "Matching provider rows (up to limit).",
"items": {
"additionalProperties": false,
"description": "A compact provider row for disambiguation.",
"properties": {
"city": {
"description": "Primary practice-location city when present.",
"type": "string"
},
"credential": {
"description": "Credential (e.g. \"MD\", \"DO\", \"RN\") when present.",
"type": "string"
},
"matchedLocation": {
"additionalProperties": false,
"description": "The additional practice location that satisfied the requested city/state/postal_code. Present only when the primary practice location is elsewhere.",
"properties": {
"city": {
"description": "City of the matching practice location.",
"type": "string"
},
"postalCode": {
"description": "Postal/ZIP code of the matching practice location.",
"type": "string"
},
"state": {
"description": "State of the matching practice location.",
"type": "string"
}
},
"type": "object"
},
"matchedOtherName": {
"additionalProperties": false,
"description": "The other (former, professional, DBA, or alternate) name this row matched the name search through. Present only when the current name fails a requested last_name, organization_name, or wildcard first_name and this other name satisfies it (case-insensitive, ignoring punctuation and spaces, trailing \"*\" as a prefix). An exact first_name alone never marks a row: the registry also matches first-name variants (Bob for Robert).",
"properties": {
"name": {
"description": "The other name as \"First Middle Last\", or its organization name.",
"type": "string"
},
"type": {
"description": "Registry name type, e.g. \"Former Name\", \"Professional Name\".",
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"name": {
"description": "Assembled \"First Last\" (individual) or organization name.",
"type": "string"
},
"npi": {
"description": "10-digit National Provider Identifier — the chaining key for npi_get_provider.",
"type": "string"
},
"postalCode": {
"description": "Primary practice-location postal/ZIP code when present.",
"type": "string"
},
"primaryTaxonomy": {
"additionalProperties": false,
"description": "The provider's primary taxonomy (the entry flagged primary, else the first listed).",
"properties": {
"code": {
"description": "Primary taxonomy code.",
"type": "string"
},
"description": {
"description": "Primary taxonomy description.",
"type": "string"
}
},
"required": [
"code"
],
"type": "object"
},
"state": {
"description": "Primary practice-location state when present.",
"type": "string"
},
"status": {
"description": "Registry status — never treat a deactivated NPI as current.",
"enum": [
"active",
"deactivated"
],
"type": "string"
},
"type": {
"description": "Provider enumeration type (NPI-1 vs NPI-2).",
"enum": [
"individual",
"organization"
],
"type": "string"
}
},
"required": [
"npi",
"type",
"name",
"status"
],
"type": "object"
},
"type": "array"
},
"resolvedTaxonomies": {
"description": "Taxonomy candidates ranked for the specialty term. The first candidate supplies appliedTaxonomyDescription; a different candidate can be selected through taxonomy_description.",
"items": {
"additionalProperties": false,
"properties": {
"code": {
"description": "Resolved NUCC taxonomy code.",
"type": "string"
},
"description": {
"description": "Search-compatible NUCC specialization or classification for this candidate.",
"type": "string"
}
},
"required": [
"code",
"description"
],
"type": "object"
},
"type": "array"
},
"shown": {
"description": "Number of providers returned.",
"type": "number"
},
"truncated": {
"description": "True when the NPPES page contained at least cap providers before location constraints were applied; more may match even when shown is below cap.",
"type": "boolean"
}
},
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:0dc46b240532d7ce8e112ece3bc395a8093492484d3f32cbca647e7a37d69cf5 | sha256sum