Configuring Search Requests
Optimize integration requests when searching for in-network providers
Ideon's "Provider Search" endpoint (API docs) enables queries against the IdeonSelect dataset using flexible criteria such as geography, specialty, and network. Well-structured search requests reduce response size, minimize unnecessary API calls, and improve both accuracy and performance of the integration. Request parameters should be aligned with the intended use case to ensure efficient and reliable integration.
Recommended Search Structure
When searching for in-network providers - providers that participate in a given plan or network - we recommend using the following search criteria as a basis for most integrations. Searches structured with the following data will produce the most consistent results across markets and geographies. Search requests as part of integrations can and should be tailored to the nuance of each use case, as necessary.
Plan or Network Identifiers - including a plan and/or network identifier in the provider search request triggers results to be evaluated and filtered for in-network providers and addresses.
Geography - filtering searches to defined geographies serves to provide users with results specific to their location as well as limiting results for endpoint performance.
Provider Specialty - one or more specialty identifiers can be included to filter results to the specific healthcare need of the user.
Provider Type - including a provider type in all requests is considered best practice for endpoint performance. This also improves end user experiences, as results will consistently be either all individual doctors or medical organizations.
Pagination - the "Provider Search" endpoint enforces a default maximum
per_pageof 25 results if no pagination parameters are passed. A maximum of 200 resultsper_pagecan be requested. Given that results are sorted by best match and pagination can significantly impact endpoint latency, we strongly recommend limiting theper_pagerequested to be in range of 25-50 results.
An example request to the "Provider Search" endpoint incorporating the above search criteria is shown below. This request can be translated to: show me all individual providers (and their in-network addresses) that participate in network ID 205757, are within 5 miles of the center point of ZIP code 10010, and are associated with specialty ID 4c12f8d69a; sort these results based on their proximity to the center point of ZIP code 10010.
{
"network_ids": [205757],
"zip_code": "10010",
"radius": 5,
"specialty_ids": ["4c12f8d69a"],
"type": "individual"
}Plan or Network Identifiers
The "Provider Search" endpoint accepts lists of network_ids and/or plan_ids in requests. If provided, the providers returned will be filtered to those that participate in at least one of the networks included. For providers returned in the response, all unique networks included in the request that they participate in - and at which addresses - is detailed.
More information on how to use network and plan IDs can be found in the Plan or Network Identifiers section. To summarize, the network_ids array expects the internal network identifiers, unique to networks in Ideon's database. The plan_ids array accepts HIOS IDs, Medicare plan identifiers (in the XXXX-XXX-X format), and internal plan identifiers. Provider participation in the response is always categorized by unique network ID; when using the plan_ids request filter, the plan-network associations must be used to map each unique network ID in the response back to its corresponding plans.
When using the plan_ids request filter, it is strongly recommended to include plan_year to ensure that results reflect in-network providers for the specified plan year. If plan_year is omitted in the request body, the request will default the value of the current calendar year.
Technically speaking, up to 100 network or plan IDs can be passed in a single provider search request. However, practical applications do not typically require this many networks to be passed in a single search.
Filtering by Geographies
There are three supported methods for defining a search area in the request. Provider search requests that include a Search Term parameter must also include a geography filter as well. Search results are limited to providers that are associated with at least one address in the geography.
ZIP Code and Radius
The zip_code and radius parameters define a search area based on the area created by drawing a radius around the center point of the ZIP code. The units for the radius parameter is miles. If a request is made with a zip_code and no radius parameter, the radius of the search will default to 25 miles.
Center Point and Radius
The center_point and radius parameters define a search area based on the area created by drawing a radius around a given point. The center_point is defined as an object with lat (latitude) and lon (longitude) values. The units for the radius parameter is miles. If a request is made with a center_point and no radius parameter, the radius of the search will default to 25 miles. The center_point offers greater flexibility than zip_code searches, and is recommended for use cases requiring precise location targeting: for example, users selecting a map pin and interacting with an adjustable radius slider.
Polygon
The polygon parameter allows custom geographic boundaries to be specified by a set of latitude and longitude points. This supports filtering to more complex geographies, and user interface components such as search to a user-defined map area. The polygon is an array of point objects defined by lat and lon; an example is given below.
Filtering by Provider Specialty
Provider specialties - pediatrics, internal medicine, etc. - are an important search criteria for provider search. Ideon's specialties are normalized according to the NUCC Specialty Code Set, which structures specialties according to three distinct "Levels" that allow for more specific areas of specialization: Provider Grouping, Classification, and Area of Specialization. This section details recommendations for effective incorporation of specialty selection into provider search workflows.
The list of specialties and codes is very infrequently updated; the full list of ~880 specialties can be pulled and manually grouped without the need for regular reviews. Given this, there are two ways to access available specialties with their name, classifications, and IDs.
The "Specialty Search" endpoint (API docs) can be used to search for specific specialties by search string or to pull all available specialties by doing a
GET /specialtieswith no search parameters included.The below file "Ideon_Specialties_Sep-4-2025.csv" contains a full list of all specialties in Ideon's database. This list includes all pertinent data returned in the "Specialty Search" endpoint as well as the relative frequency that each specialty is observed in carrier source data.
Grouping Specialties
For the majority of use cases, we highly recommend maintaining predefined provider specialty groupings in order to present users with specialty options that are more intuitive to choose from.
Use Cases
Broader search coverage - Creating a category such as "Cardiology Services" that encompasses Ideon specialties like "Nuclear Cardiology" and "Interventional Cardiology" enables users to search for all providers associated with granular specialties under a broader umbrella.
Combined category searches - Specialty groupings allow searches that span multiple broader categories. For example, a search for "Pediatric Allergist" can return providers by querying all specialties under both "Pediatrics" and "Allergy and Immunology Services".
Flexible granularity - The option to offer a more specific specialty selection can always be offered as a second step in this process. For more targeted results, enable your users to select multiple individual specialties alongside predefined groups in their provider search query.
The below file contains a full list of all available specialty taxonomies grouped into broader categories as a reference point to help guide your integration. These can be adopted as is or customized based on your specific user experience requirements.
As the list of available specialties from Specialty Search is infrequently updated, we recommend caching this data to reduce potential latency.
Specialty IDs Filter
The "Provider Search" endpoint accepts an array of the internal specialty IDs (specialty_ids) - found in the id field in the "Specialty Search" endpoint or the specialty_id field in the above CSV.
We highly recommend limiting the number of specialty IDs included in any given provider search request to 20 or less. This allows for all specialty grouping use cases to be achieved while also optimizing the performance of the provider search endpoint. If more than 20 specialty IDs need to be searched for, we recommend making multiple endpoint requests to iterate through the specialties in groups of 20.
Provider Type
The type parameter filters results to one of individual (individual doctors), organization (medical groups, urgent care, etc), or hospital provider records. We highly recommend including this parameter for all provider search requests for two reasons. First, it can reduce results, making it easier to select the desired provider. Second, including type significantly improves endpoint response latency.
Last updated
Was this helpful?