Provider Search Responses

Interpret provider results when searching for in-network providers

The "Provider Search" endpoint (API docs) returns filtered and ranked results for providers based on the search criteria passed. The response is structured as a list of provider objects, each with complete provider metadata and address information. When a request is made with plan and/or network IDs included, responses will be filtered to providers that participate in at least one of the requested networks. Additionally, the network and network_ids will be rendered in the response schema, detailing the participating networks and addresses for each provider. This page includes sections outlining important information and tips on how to best integrate provider search responses into user-facing interfaces.

Result Schema and Data Dictionary

Responses in the "Provider Search" endpoint are structured as an array of provider objects. The response schema is fully documented in the technical API docs as well as the Provider Data Dictionary section. It is important to note that the networks array is only rendered in the provider search response if a plan or network ID is included in the request.

In addition to the fields documented in the Data Dictionary, all unique addresses that are are included in any of the networks[].addresses arrays are included in a top-level addresses array. The schema for the address objects in this array matches the schema in the Data Dictionary's Addresses section. However, the network-specific address fields (pcp, pcp_id, external_id, and accepting_new_patients) are all returned as null in the top-level addresses array.

Last Imported Date

The last_imported_at date is included for each network in the networks array. The date represents the ISO 8601 timestamp indicating when the data for the associated network was last acquired, QA'd, and published. This date is a proxy for network health by communicating the recency of data refresh or conversely, how stale the data for the given network is. For most use cases, we recommend considering a warning flag to users if the last_imported_at date is more than three months prior to the current date. This warning flag can suggest that users verify provider participation by calling the office before making a decision critical to their healthcare.

Provider Address Filtering

When searching for in-network providers, providers are included if the participate in the searched network(s) at one or more addresses within the defined geographies. All of the addresses that the matched provider practices at and participates in the network at are included in the networks[].addresses array. The top-level addresses array contains all unique addresses for the provider in each of the associated networks[].addresses array for the given search.

Ranking and Sorting of Results

The "Provider Search" endpoint supports two methodologies for ranking, or sorting, of results: a multi-faceted best match function and a strict distance evaluation. The default for any request is to rank by best match, which can also be defined by passing the sort parameter as best_match. A ranking with higher weights on provider address distance can be requested by passing the sort parameter as distance.

Both ranking methodologies evaluate the following parameters, if included in the search request.

• The distance to the center point of the defined geography. This considers all addresses for the providers; the address closest to the geography's center point is used for ranking.

• The closeness of the provider_name_search term match.

• Provider specialty match, when searching without a plan or network ID. All specialties associated with a provider - from NPPES and all carrier sources - are considered when filtering a search based on specialty. Ranking weighs a match against the carrier (or network) specialties higher than the NPPES specialty when searching for providers with a plan or network ID included.

The best_match methodology weighs all above criteria, if included, for searches with a plan or network ID. The distance methodology also considers all the above parameters, but weighs provider distance significantly higher.