> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perfectreferral.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get practitioner by NPI number
> Returns information about the practitioner associated with the provided NPI number.
Returns information about the practitioner associated with the provided NPI number.
The response includes:
* **Specialties**: reported by NPPES
* **Referral scope matches**: proprietary information about whether the provider is an appropriate candidate for a routine referral for a specific performable or procedure
A non-match (`unlikely_match` or `very_unlikely_match`) means a routine referral target does not fit the provider's observed billing. It does not mean the service is outside their scope of practice or that they are unqualified; it reflects what they routinely bill, not what they are licensed or trained to do.
This endpoint serves individual practitioners (NPI-1) only.
## OpenAPI
````yaml https://api.perfectreferral.com/v1/openapi.yml get /practitioners/{npiNumber}
openapi: 3.1.0
info:
version: 1.0.0
title: Perfect Referral
description: Refer patients to the right specialist the first time.
contact:
email: support@perfectreferral.com
servers:
- url: https://api.perfectreferral.com/v1
security:
- bearerHttpAuthentication: []
tags:
- name: Practitioner
- name: Specialization
paths:
/practitioners/{npiNumber}:
get:
tags:
- Practitioner
summary: Get practitioner by NPI number
description: >-
Returns information about the practitioner associated with the provided
NPI number.
operationId: getPractitionerByNpiNumber
parameters:
- name: npiNumber
in: path
required: true
description: >-
The 10-digit number corresponding to NPPES registration for the
practitioner of interest. Must also correspond to NPI Type
Individual (NPI-1) - see
https://npiregistry.cms.hhs.gov/help/help-home for more information.
schema:
type: string
pattern: ^[0-9]{10}$
minLength: 10
maxLength: 10
- name: model
in: query
required: false
description: The desired model to use.
schema:
type: string
default: latest
responses:
'200':
description: Expected response to a valid request
headers:
X-Ratelimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-Ratelimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-Ratelimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
content:
application/json:
schema:
$ref: '#/components/schemas/PractitionerReferralScopeMatches'
example:
name: Dr. Naomi Park
nppesSpecialties:
- 207WX01070
referralScopeMatches:
- specialty: Ophthalmology
target: Medical and surgical retina care
label: very_likely_match
'400':
description: The request was malformed (e.g. invalid path parameter).
headers:
X-Ratelimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-Ratelimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-Ratelimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: '400'
message: Invalid NPI number format.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: No specialization found for the given number.
headers:
X-Ratelimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-Ratelimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-Ratelimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: '404'
message: No practitioner found for the given NPI number
'422':
description: >-
The NPI number refers to an organization (NPI-2); this endpoint
serves individual practitioners (NPI-1) only.
headers:
X-Ratelimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-Ratelimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-Ratelimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: '422'
message: NPI number must correspond to an individual (NPI-1)
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalError'
5XX:
$ref: '#/components/responses/ServerError'
security:
- bearerHttpAuthentication: []
components:
headers:
RateLimitRemaining:
description: Requests left in the current monthly quota window.
schema:
type: integer
RateLimitReset:
description: Unix time (seconds) when the monthly quota window resets.
schema:
type: integer
RateLimitLimit:
description: Total requests allowed per monthly quota window.
schema:
type: integer
RetryAfter:
description: Seconds to wait before retrying.
schema:
type: integer
schemas:
PractitionerReferralScopeMatches:
type: object
required:
- name
- nppesSpecialties
- referralScopeMatches
properties:
name:
type: string
description: The name of the practitioner, as reported by NPPES.
nppesSpecialties:
type: array
description: >-
An array of NUCC Provider Taxonomy codes
(https://www.nucc.org/index.php/code-sets-mainmenu-41/provider-taxonomy-mainmenu-40)
for the practitioner, as reported by NPPES.
items:
type: string
referralScopeMatches:
type: array
description: >-
One estimate per routine referral target evaluated for this
practitioner. Each entry pairs a target with a label describing how
well the practitioner fits it as a destination, derived from
observed Medicare and Medicaid billing rather than from what their
license or self-reported specialty permits.
items:
$ref: '#/components/schemas/ReferralScopeMatch'
Error:
type: object
required:
- code
- message
properties:
code:
type: string
description: HTTP status error code.
message:
type: string
description: Human-readable error description.
ReferralScopeMatch:
type: object
required:
- specialty
- target
- label
properties:
specialty:
type: string
description: >-
The specialty or subspecialty that `referralScopeMatch.target`
belongs to.
target:
type: string
description: >-
The routine referral reason within `referralScopeMatch.specialty`
being evaluated: a focus area, a common procedure, or the catch-all
"generalist" target for the specialty.
label:
type: string
description: >
Our estimate of whether the practitioner is an appropriate match for
the target, based on their observed billing. Predictive values are
calibrated against an even sampling of held-out providers in the
target's specialty.
- `very_likely_match`: strongly indicates a match (at least 95%
predictive value).
- `likely_match`: indicates a match (at least 80% predictive value).
- `uncertain`: evaluable, but the evidence supports neither a match
nor a no-match call.
- `unlikely_match`: indicates this is not a match (at least 80%
predictive value).
- `very_unlikely_match`: strongly indicates this is not a match (at
least 95% predictive value).
- `insufficient_data`: not enough billing data to evaluate.
`uncertain` and `insufficient_data` are not negative signals; treat
both as a "no confident call." `uncertain` means the evidence was
mixed; `insufficient_data` means there was too little billing data
to judge.
enum:
- very_likely_match
- likely_match
- uncertain
- unlikely_match
- very_unlikely_match
- insufficient_data
responses:
Unauthorized:
description: API token missing or invalid.
headers:
X-Ratelimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-Ratelimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-Ratelimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: '401'
message: Unauthorized
TooManyRequests:
description: >-
Too many requests. Returned when either the monthly request quota or the
per-second request-rate limit is exceeded; the `message` field
distinguishes them ("rate limit exceeded" is the monthly quota, "request
rate exceeded" is the per-second limit).
headers:
X-Ratelimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-Ratelimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-Ratelimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: '429'
message: Too Many Requests
InternalError:
description: Unexpected server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: '500'
message: Unexpected server error
ServerError:
description: Server error.
securitySchemes:
bearerHttpAuthentication:
description: >-
Bearer authentication header of the form `Bearer `, where
`` is your API token.
type: http
scheme: bearer
````