Search for Providers


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-f9a4ab924d9d
  • insurance_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:

addressString input of an address that will be interpreted and geocoded in real time.
specialty_idsComma separated list of desired specialty uuids. See all providers who specialize in the given specialties.
specialtyString 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_primaryComma separated list of specialty uuids. See all providers whose primary specialties are in the given specialties.
specialty_primaryString 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_idsComma separated list of desired insurance uuids. See all providers who accept a given insurance(s).
insurance_carrier_nameString 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
nameString input of a full, first, last, or partial name.
location_idsComma separated list of desired practice location uuids. See all providers who see patients at any of the given practice locations.
location_insurance_idsComma 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.
locationLatitude/longitude pair of coordinates in lieu of a string address (i.e. location=37.7489816,-122.4802092).
npisComma 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_typesComma 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_confidenceInteger 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_confidenceInteger 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.
genderString input of either m or f to filter to only medical providers of the inputted gender.
max_ageInteger input (i.e. 50) to filter to only medical providers under the inputted age.
min_ageInteger input (i.e. 50) to filter to only medical providers above the inputted age.
languageFuzzy 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_distanceSet to true to exclude providers' locations that are outside of the search radius (distance) when searching using an address. Defaults to false.
min_ratingInteger input (from 0 to 10) to filter to only providers above the inputted value for the ratings_avg field.
national_bluecardDefaults 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_ids parameter, you could also use the specialty parameter 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 \
  ' 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_distance parameter 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_count shows 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": [
        "insurance_ids": [
  "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": [...],
      "online_profiles": [...],
      "distance": 0.04,
      "npi": "1992964035"
...24 more Doctors...