---
title: "Search Providers"
method: GET
path: "/patients/v1/search_providers"
tags: ["v1"]
---

# Search Providers

`GET /patients/v1/search_providers`

## Request

- Base URL: `https://pre-api.joincandidhealth.com`
- URL: `https://pre-api.joincandidhealth.com/patients/v1/search_providers`
- Auth: HTTP bearer

Searches for referring providers that match the query parameters.  The search is case-insensitive, supports fuzzy matching, and matches against provider name and NPI. The search criteria must be an alphanumeric string, and the search is limited to the first 20 results.

## Query parameters

- `search_criteria` string, required

## Response `200`

Response with status 200

- PreEncounterCommonExternalProvider[]
  - `name` PreEncounterCommonHumanName, required
    - `family` string, required
    - `given` string[], required
    - `use` 'USUAL' | 'OFFICIAL' | 'TEMP' | 'NICKNAME' | 'ANONYMOUS' | 'OLD' | 'MAIDEN', required
    - `period` PreEncounterCommonPeriod
      - `start` string, date
      - `end` string, date
    - `suffix` string
  - `type` 'PRIMARY' | 'REFERRING' | 'ATTENDING'
  - `npi` string
  - `telecoms` PreEncounterCommonContactPoint[], required
    - `value` string, required
    - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'MOBILE', required
    - `period` PreEncounterCommonPeriod
      - `start` string, date
      - `end` string, date
  - `addresses` PreEncounterCommonAddress[]
    - `use` 'HOME' | 'WORK' | 'TEMP' | 'OLD' | 'BILLING', required
    - `line` string[], required
    - `city` string, required
    - `state` string, required
    - `administrative_area` string: The top-level administrative subdivision of the country for addresses outside the US — for example a Canadian province, a UK county, or a Japanese prefecture. Only permitted on international addresses: `country` must be present and non-US, and `state` must be "FC" (the X12 foreign-country sentinel). For US addresses use `state` instead.
    - `postal_code` string, required
    - `country` string, required
    - `county` string
    - `period` PreEncounterCommonPeriod
      - `start` string, date
      - `end` string, date
  - `period` PreEncounterCommonPeriod
    - `start` string, date
    - `end` string, date
  - `canonical_id` string: The unique identifier for a provider configured in the Candid system
  - `fax` string
  - `other_fax_numbers` string[]
  - `emails` string[]
  - `service_facilities` PreEncounterCommonPatientServiceFacility[]: Associated service facilities for this provider.
    - `service_facility_id` string, required: The unique identifier for a service facility configured in the Candid system

## Changes

- **2026-09-19** `72fc5ca65ba5`: 1 info
  - added the optional property `items/addresses/items/administrative_area` to the response with the `200` status
- **2026-09-17** `24b2d80d577a`: 1 breaking, 1 warning, 12 info
  - the `items/` response's property type changed from no type to `object` for status `200`
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `OAuthScheme` was added to the API
  - added the optional property `items/addresses` to the response with the `200` status
  - …10 more
- **2026-09-12** `3a81ee81d4ed`: 1 info
  - api operation id `search_providers` removed and replaced with `v1_search_providers`

[Operation history](https://skmtc.dev/joincandidhealth/apis/api-reference/changes/patients/v1/search_providers/get.md)

---

[API](https://skmtc.dev/joincandidhealth/apis/api-reference.md) - [All operations](https://skmtc.dev/joincandidhealth/apis/api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/joincandidhealth/apis/api-reference/revisions/d8b0a61873e2?raw)