---
title: "Lookup Provider"
method: POST
path: "/provider/lookup"
tags: ["public-api"]
---

# Lookup Provider

`POST /provider/lookup`

Look up a provider by NPI or by name+state.

NPI mode: returns ``active``, ``deactivated`` (with name+state search
candidates seeded from the deactivated record's name), ``not_found``, or
``registry_error``. Sandbox organizations may receive an ``active``
mock identity when the NPI is absent from the registry. Deactivated
records with no name on file return an empty candidate list — the FE
prompts for manual name+state entry.

Name mode: ``last_name`` is required, ``first_name`` and ``state`` are
optional. Always returns ``search_results`` (the candidate list may be
empty when no match is found).

## Request body

- ProviderLookupRequest — Body for ``POST /provider/lookup``. Either ``npi`` or a ``last_name`` must be supplied. NPI lookup branches on the registry's ``status`` value and may return active, deactivated (with name+state search candidates), not_found, or registry_error. Optional names may accompany NPI lookup as hints for sandbox mock-NPI fallback. A name+state body without NPI always returns search_results.
  - `npi` string — The NPI to look up. Optional names may be included as sandbox fallback hints.
  - `first_name` string — First name for name+state search. Optional when last_name is provided.
  - `last_name` string — Last name for name+state search. Required for name search.
  - `state` string — Two-letter state abbreviation. Optional in name searches.

## Response `200`

Successful Response

- ApiResponseProviderLookupResponse
  - `status` union
    - 'success'
    - 'error'
  - `error` ApiError
    - `title` string, required
    - `description` string, required
    - `code` string, required
  - `data` ProviderLookupResponse — Response shape for ``POST /provider/lookup``. The fields populated depend on ``status``: - ``active``: ``individual`` is set; ``candidates`` is empty. - ``deactivated``: ``individual`` is the deactivated identity; ``candidates`` is the active replacements found via name+state search (may be empty when the deactivated record has no name on file). - ``not_found`` / ``registry_error``: both fields empty. - ``search_results``: ``candidates`` lists active matches; ``individual`` is empty.
    - `status` 'active' | 'deactivated' | 'not_found' | 'registry_error' | 'search_results', required — Outcome of a provider lookup or search.
    - `individual` ProviderIdentitySchema — Identity fields surfaced from a registry record.
      - `npi` string, required
      - `first_name` string, required
      - `last_name` string, required
      - `middle_name` string
      - `name_prefix` string
      - `name_suffix` string
      - `credential` string
      - `status` string, required — Registry status code: 'A' or 'D'.
      - `practice_address` OptionalAddress — Represents a postal address with optional fields. Used for cases where address information may not be complete at creation time.
        - `street` string — Street address of residence.
        - `street_line_2` string — Additional street address information.
        - `city` string — City of residence.
        - `state_province` string — State or province of residence.
        - `zip_postal_code` string — ZIP or postal code part of the address.
        - `country` string — Country of residence.
      - `addresses` PracticeLocation[] — All practice locations the registry has for this provider, in the order CMS reports them. Each location pairs the postal address with the phone/fax recorded for it.
        - `address` OptionalAddress, required — Represents a postal address with optional fields. Used for cases where address information may not be complete at creation time.
          - `street` string — Street address of residence.
          - `street_line_2` string — Additional street address information.
          - `city` string — City of residence.
          - `state_province` string — State or province of residence.
          - `zip_postal_code` string — ZIP or postal code part of the address.
          - `country` string — Country of residence.
        - `phone` string — The phone number the registry has for this practice location.
        - `fax` string — The fax number the registry has for this practice location.
    - `candidates` ProviderIdentitySchema[]
      - `npi` string, required
      - `first_name` string, required
      - `last_name` string, required
      - `middle_name` string
      - `name_prefix` string
      - `name_suffix` string
      - `credential` string
      - `status` string, required — Registry status code: 'A' or 'D'.
      - `practice_address` OptionalAddress — Represents a postal address with optional fields. Used for cases where address information may not be complete at creation time.
        - `street` string — Street address of residence.
        - `street_line_2` string — Additional street address information.
        - `city` string — City of residence.
        - `state_province` string — State or province of residence.
        - `zip_postal_code` string — ZIP or postal code part of the address.
        - `country` string — Country of residence.
      - `addresses` PracticeLocation[] — All practice locations the registry has for this provider, in the order CMS reports them. Each location pairs the postal address with the phone/fax recorded for it.
        - `address` OptionalAddress, required — Represents a postal address with optional fields. Used for cases where address information may not be complete at creation time.
          - `street` string — Street address of residence.
          - `street_line_2` string — Additional street address information.
          - `city` string — City of residence.
          - `state_province` string — State or province of residence.
          - `zip_postal_code` string — ZIP or postal code part of the address.
          - `country` string — Country of residence.
        - `phone` string — The phone number the registry has for this practice location.
        - `fax` string — The fax number the registry has for this practice location.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/develophealth/apis/develop-health-public-api.md) · [All operations](https://skmtc.net/develophealth/apis/develop-health-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/develophealth/develop-health-public-api/revisions/1684e1dda9be/schema)