Search for Providers
Overview
Description: The listings and search endpoint allows you to quickly pull doctors based on important search criteria.
Endpoint: /v1/custom/providers
Status: Live
Methods: GET
Example use-case: Build a listing of doctors for a user searching for doctors based on important parameters like specialty, location within walking distance, user's insurance, patient satisfaction, etc. You can also search for fields that you create yourself at the /v1/custom/doctors/filters endpoint!
Diving In
The providers API allows you to pull information on nearby doctors anywhere in the United States, ranging from basics like location and contact information to granular detailed information on the doctor like accepted insurance and patient satisfaction ratings.
To start with an example, the '/v1/custom/providers' endpoint responds with a list of providers sorted by proximity from the given address. Let's say we want to find a doctor in New York City whose primary specialty is cardiology and accepts a specific Aetna insurance.
To see it in action, we are going to enter in three parameters in this query:
address=New York, NY.specialty_ids_primary=1de33770-eb1c-47fa-ab3e-f9a4ab924d9dinsurance_ids=2d5231c0-2d29-4026-9138-5dcbd0591404
With these parameters, we're searching for Cardiovascular Doctors in the New York area who accept Aetna - Choice Plus II
Primary Specialties
A provider’s primary specialty is designated by NPPES and other relevant sources. By default, Ribbon will only designate one specialty as the primary specialty for a provider. However, you are able to set more specialties as primary using this endpoint:
/v1/custom/providers/{npi}/specialties/{uuid}
Search Parameters
You can search for providers based on any of the core fields associated with a provider (i.e. name, age, gender, etc.). You can also use the following parameters for more involved searches:
| Parameter | Description |
|---|---|
address | String input of an address that will be interpreted and geocoded in real time. |
specialty_ids | Comma separated list of desired specialty uuids. See all providers who specialize in the given specialties. |
specialty | String input of a provider specialty that will be interpreted and matched to the single closest specialty, dealing with basic typos and colloquial names for providers. For example, to find Gastroenterologists you could search any of the following: - gastroenterology - gastroenterologist - gastro - stomach doc - gastrooentrology |
specialty_ids_primary | Comma separated list of specialty uuids. See all providers whose primary specialties are in the given specialties. |
specialty_primary | String input of a provider specialty that will be interpreted and matched to the single closest specialty, similar to the "specialty" parameter. See all providers whose primary specialty is the given specialty. |
insurance_ids | Comma separated list of desired insurance uuids. See all providers who accept a given insurance(s). |
insurance_carrier_name | String input of carrier_name in order to search for all providers that take at least one plan from a given insurance carrier. Find the individual valid carrier_name values from the insurance objects returned in the Insurances Reference Endpoint. Note: This input must be an exact string match to work |
name | String input of a full, first, last, or partial name. |
location_ids | Comma separated list of desired practice location uuids. See all providers who see patients at any of the given practice locations. |
location_insurance_ids | Comma separated list of desired insurance uuids. See all provider locations that accept a given insurance(s). Note, this parameter cannot be combined with insurance_ids to filter on provider insurances and provider location insurances. |
location | Latitude/longitude pair of coordinates in lieu of a string address (i.e. location=37.7489816,-122.4802092). |
npis | Comma separated list of desired NPIs (i.e. use this to search for 5 specific doctors). Note: This parameter cannot be used in combination with any other parameters. All other parameters will be ignored. |
provider_types | Comma separated list of the 'types' of providers you are searching for. Provider types are higher level groupings of specialties. Here are a few key provider types: - Doctor - Nursing - Dental Providers - Optometry - Chiropractic Providers See the Specialties Reference Endpoint for a list of all specialties and their provider types. |
min_location_confidence | Integer input (0-5) of the minimum confidence threshold for returned provider locations. min_location_confidence=3 will only display providers' locations that have a confidence 3 or higher. If a provider has a 5 locations, one of which is greater than 3, only the high confidence location will be included in the returned JSON output.Note: when this parameter is in use, the maximum number of records accessible is 1000 (i.e. if you maintain the default page_size of 25, the last page that can be paginated to is 40) |
min_confidence | Integer input (0-5) of the minimum confidence location you wish the returned providers to have (i.e. min_confidence=4 will only display providers who have a location with confidence 4 or higher). This is a more performant but 'simpler' version of min_location_confidence parameter. |
gender | String input of either m or f to filter to only medical providers of the inputted gender. |
max_age | Integer input (i.e. 50) to filter to only medical providers under the inputted age. |
min_age | Integer input (i.e. 50) to filter to only medical providers above the inputted age. |
language | Fuzzy search based on a string input (i.e. English) to filter to only medical providers providers who speak / whose office staff speak the inputted language. |
location_within_distance | Set to true to exclude providers' locations that are outside of the search radius (distance) when searching using an address. Defaults to false. |
min_rating | Integer input (from 0 to 10) to filter to only providers above the inputted value for the ratings_avg field. |
national_bluecard | Defaults to true unless otherwise specified. Boolean input that enables an API search to automatically default to the National BlueCard EPO/PPO Network whenever a member searches for out-of-state, in-network care and is covered by a BCBS Association PPO insurance plan. Use the parameter in conjunction with the address parameter and either the insurance_ids or insurance fuzzy search parameters. |
Provider Board Certifications & Specialties
Ribbon has partnered with the American Board of Medical Specialties® (ABMS) to confirm board certifications for relevant physicians and cross reference physician specialty.
To learn more about what ABMS board certification means, click here.
This information is proprietary data maintained in a copyrighted database compilation owned by the American Board of Medical Specialties. Copyright 2020 American Board of Medical Specialties. All rights reserved.
Searching Specialty by String
Instead of using the
specialty_idsparameter, you could also use thespecialtyparameter which interprets a string value for each specialty. For example, instead of using the specialty uuid for Cardiovascular doctor, the following calls would work as well:
Using Specialty Related Search Parameters
Primary specialty search parameters (
specialty_primary,specialty_ids_primary) cannot be used in tandem with the regular specialty search parameters (specialty,specialty_ids)
Example Request
curl -X GET \
'https://api.ribbonhealth.com/v1/custom/providers?address=33 Irving Pl, NYC&specialty_ids=1de33770-eb1c-47fa-ab3e-f9a4ab924d9d&insurance_ids=2d5231c0-2d29-4026-9138-5dcbd0591404' \
-H 'authorization: Bearer <your_token>'
The JSON object response to the above query is below. This response includes a list of 20 doctors under results. The response includes typical pagination links under next and previous.
We can also see what parameters are driving the query under parameters, which can be useful in making sure that the search parameters you're passing are properly received. You'll notice a few new components in the parameters that were not originally passed into the query.
1) geo includes longitude & latitude coordinates interpreted from the given address. This helps us understand the central location that distance is being calculated for each doctor. In this case, we see that the string New York, NY resulted in Latitude, Longitude coordinates of 40.7351327, -73.9903544.
2) distance shows the proximity radius of doctors displayed. We can see here that the API is using a default, which is a distance radius of 10 miles. If this radius is too narrow or too broad, it can be configured with the distance parameter. Note: when using min_location_confidence and location_insurance_ids parameters, limit distance to be less than 50 miles to ensure high quality results.
Providers can have multiple locations, be careful to only display those that are relevant!
When you search for providers at the /providers/ endpoint with an address/location inputted, the API will return a list of providers who have a service location within the given search radius (default search radius is 10 miles if unspecified). However, providers often have multiple service locations and the API will return all locations that the provider is listed at. The list of providers returned is ordered based on distance with the closest providers appearing first, and also within each provider profile their locations are ordered in ascending format based on the distance to the address/location inputted.
To exclude locations outside of the search radius, add the
location_within_distanceparameter and set it true along with your search. Otherwise, we recommend only showing the first location when determining which location to display for each individual provider, as that first location is the 'reason' the provider is appearing in the search where they are.
total_countshows the number of results returned for the given search
{
"parameters": {
"total_count": 141,
"page": 1,
"page_size": 25,
"sort_by": "distance",
"distance": 10,
"geo": {
"latitude": 40.7351327,
"longitude": -73.9881657
},
"address": "33 Irving Pl, New York, NY 10003, USA",
"specialty_ids": [
"1de33770-eb1c-47fa-ab3e-f9a4ab924d9d"
],
"insurance_ids": [
"2d5231c0-2d29-4026-9138-5dcbd0591404"
]
},
"data": [
{
"first_name": "Alexander",
"middle_name": "J",
"last_name": "Greenstein",
"age": 42,
"gender": "m",
"ratings_count": 38,
"ratings_avg": 8.74,
"degrees": [...],
"specialties": [...],
"languages": [...],
"educations": [...],
"insurances": [...],
"provider_types": [...],
"locations":[...],
"online_profiles": [...],
"distance": 0.04,
"npi": "1992964035"
},
...24 more Doctors...
]
}
Updated 26 days ago