> ## 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 location by id

> Returns detailed information about a single practitioner location, including the sources that report that the practitioner practices at this location.

Returns detailed information about a single practitioner location, identified by the `id` returned in the `locations` array of the [Get practitioner by NPI number](/api-reference/practitioner/get-practitioner-by-npi-number) endpoint.

The response includes:

* **Address**: the street address, city, state, and postal code for the location
* **Geocoding**: coordinates for the location's address, when available
* **Stale affiliation risk**: proprietary information about whether the practitioner is actually seeing patients at this location
* **Sources**: each dataset that reports that the practitioner practices at this location, with its version and the date of the pipeline run that produced it

<Info>
  Geocoding data is provided in part by OpenStreetMap. © OpenStreetMap contributors, available under the [Open Database License (ODbL)](https://opendatacommons.org/licenses/odbl/). Additional data is derived from the U.S. Census Bureau TIGER/Line® Shapefiles (public domain), from other public sources, and from proprietary sources, such as Geocodio.
</Info>


## OpenAPI

````yaml https://api.perfectreferral.com/v1/openapi.yml get /practitioner-locations/{id}
openapi: 3.1.0
info:
  version: 1.1.0
  title: Perfect Referral
  description: Refer patients to the right specialist the first time.
  contact:
    email: support@threshold.health
servers:
  - url: https://api.perfectreferral.com/v1
security:
  - bearerHttpAuthentication: []
tags:
  - name: Model
  - name: Practitioner
  - name: Practitioner Location
  - name: Specialization
paths:
  /practitioner-locations/{id}:
    get:
      tags:
        - Practitioner Location
      summary: Get practitioner location by id
      description: >-
        Returns detailed information about a single practitioner location,
        including the sources that report that the practitioner practices at
        this location.
      operationId: getPractitionerLocationById
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            The id corresponding to the practitioner location. These can be
            found in the `locations` objects within the [Get practitioner by NPI
            number](/api-reference/practitioner/get-practitioner-by-npi-number)
            endpoint.
          schema:
            type: string
            format: uuid
        - name: staleAffiliationRiskVersion
          in: query
          required: false
          description: >-
            The version of the stale affiliation risk model to use, as
            enumerated by `GET /models`. Defaults to the latest version if
            omitted.
          schema:
            type: string
      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/PractitionerLocation'
              example:
                line1: 123 Main Street
                city: San Diego
                state: CA
                postalCode: '92103'
                geocoding:
                  latitude: 32.7469572
                  longitude: -117.1663201
                staleAffiliationRisk:
                  label: very_likely_active
                sources:
                  - name: CMS National Provider Directory
                    version: '20260507'
                    observedAt: '2026-07-20T21:21:49Z'
                  - name: NPPES
                    version: '20260712'
                    observedAt: '2026-07-30T22:13:13Z'
                servedModels:
                  staleAffiliationRisk: v1.0
        '400':
          description: >-
            The request was malformed: for example, an invalid location id or an
            unknown model version.
          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 path parameter "id"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No practitioner location found for the given id.
          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 location found for the given id
        '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:
    PractitionerLocation:
      type: object
      description: >-
        A single practitioner–location pair, including the address, our derived
        signals, and the sources that report it.
      required:
        - line1
        - city
        - state
        - postalCode
        - sources
        - servedModels
      properties:
        line1:
          type: string
          description: >-
            The first line of the street address, typically the street number
            and name.
        line2:
          type: string
          description: >-
            The second line of the street address, when present, such as a
            suite, unit, or floor.
        city:
          type: string
          description: The city name.
        state:
          type: string
          description: The two-letter USPS abbreviation for the state or territory.
        postalCode:
          type: string
          description: The postal (ZIP) code, in the five digit form.
        geocoding:
          $ref: '#/components/schemas/Geocoding'
        staleAffiliationRisk:
          $ref: '#/components/schemas/StaleAffiliationRisk'
        sources:
          type: array
          description: >-
            The datasets that report that the practitioner practices at this
            location.
          items:
            $ref: '#/components/schemas/Source'
        servedModels:
          type: object
          description: >-
            The version of each model whose output appears in this response.
            Always present; a key appears only when that model was served for
            this request, so an absent key means that model contributed nothing
            to the response.
          properties:
            staleAffiliationRisk:
              type: string
              description: >-
                The version that produced the `staleAffiliationRisk` label.
                Omitted when no stale affiliation risk model was served for this
                request.
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: HTTP status error code.
        message:
          type: string
          description: Human-readable error description.
    Geocoding:
      type: object
      required:
        - latitude
        - longitude
      description: Geocoding data for the location's address, if available.
      properties:
        latitude:
          type: number
        longitude:
          type: number
    StaleAffiliationRisk:
      type: object
      required:
        - label
      description: >-
        Stale affiliation risk data for this practitioner–location pair, if
        available.
      properties:
        label:
          type: string
          description: >
            Our estimate of whether the practitioner is actually seeing patients
            at this location, based on public federal sources such as monthly
            Medicare billing histories and NPPES registry data, and calibrated
            against independently verified practitioner–location pairs.


            - `very_likely_active`: strongly indicates the practitioner is
            seeing patients at this location.

            - `likely_active`: indicates the practitioner is seeing patients at
            this location.

            - `uncertain`: the evidence supports neither an active nor an
            inactive call.

            - `likely_inactive`: indicates the practitioner is not seeing
            patients at this location.

            - `very_likely_inactive`: strongly indicates the practitioner is not
            seeing patients at this location — the listing is stale or was never
            patient-facing.


            Unlike referral scope matches, these labels do not carry fixed
            predictive values: the probability that a labeled listing is wrong
            depends on the baseline wrong rate of the directory it appears in.
            See the [stale location
            methodology](https://docs.perfectreferral.com/methodology/stale-location)
            to convert labels into probabilities for your directory, and for
            sources and limitations. Predictions are regenerated monthly.
          enum:
            - very_likely_active
            - likely_active
            - uncertain
            - likely_inactive
            - very_likely_inactive
    Source:
      type: object
      required:
        - name
        - version
        - observedAt
      properties:
        name:
          type: string
          description: The human-readable name of the dataset that reported the location.
        version:
          type: string
          description: The version (vintage) of the dataset that reported the location.
        observedAt:
          type: string
          format: date-time
          description: When the pipeline run that produced this location was executed.
  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
    Forbidden:
      description: >-
        The caller cannot access a model version required to serve this request:
        either the requested version is above their tier, or no version of a
        required model is available to them.
      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: '403'
            message: pro tier required to access this model
    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 <token>`, where
        `<token>` is your API token.
      type: http
      scheme: bearer

````