Search Providers

get https://api.ribbonhealth.com/v1/custom/providers

Allows you to quickly list doctors based on important search criteria.

time	status	user agent
Retrieving recent requests…

Loading…

Query Params

Pagination and Search Configuration Options

object

Options to control what data gets returned to you.

Provider Search Criteria

object

Search criteria based on aspects of the providers themselves.

Location Search Criteria

object

Criteria used to search for providers based on the locations at which they practice.

Insurance Search Criteria

object

Criteria used to search for providers based on the insurances they accept.

Specialty Search Criteria

object

Criteria used to search for providers based on their specialties.

Procedure Search Criteria

object

Criteria used to search for providers based on procedures they perform.

Focus Area Search Criteria

object

Criteria used to search for providers based on their Focus Areas.

Cost and Quality Criteria

object

Criteria used to search for providers based on Cost and Quality scores.

Organization Search Criteria

object

Criteria used to search for providers based on the organizations they belong to.

TINs Search Criteria

object

Criteria used to search for providers based on the TINs they are associated with.

Responses

Response body

object

parameters

object

required

total_count

integer

The total number of results matched, across all pages.

sort_by

string

The main criteria used to sort results in the record set.

geo

object

page

integer

The page of the results which was returned.

page_size

integer

How many results are in each page.

max_locations

integer

The maximum number of locations attached to any given provider. Defaults to 5 (not shown if unspecified).

fields

array of strings

List of fields within the provider object to return. Can be used to greatly reduce the size of the response by requesting only data you intend to use.

Cannot be used in tandem with _excl_fields

fields

_excl_fields

array of strings

List of fields within the provider object to exclude from the response. Can be used to greatly reduce the size of the response by requesting only data you intend to use.

_excl_fields

npis

array of strings

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.

npis

name

string

String input of a full, first, last, or partial name.

provider_types

array of strings

The 'types' of providers you searched 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.

provider_types

gender

string

String input of either m or f to filter to only medical providers of the inputted gender.

m f

max_age

integer

Integer input (i.e. 50) to filter to only medical providers under the inputted age.

min_age

integer

Integer input (i.e. 50) to filter to only medical providers above the inputted age.

language

object

min_rating

integer

0 to 10

Integer input (from 0 to 10) to filter to only providers above the inputted value for the ratings_avg field.

address

string

String input of an address that will be interpreted and geocoded in real time.

location_ids

array of strings

List of desired practice location uuids. See all providers who see patients at any of the given practice locations.

location_ids

min_location_confidence

integer

0 to 5

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

0 to 5

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.

distance

integer

The proximity radius of providers returned.

Note: When using min_location_confidence and location_insurance_ids parameters, limit distance to be less than 50 miles to ensure high quality results.

state

string

Two-letter state abbreviation of provider locations to filter to. Note that this parameter will override address and location parameters if used together.

insurance_ids

array of strings

List of desired insurance uuids. See all providers who accept a given insurance(s).

insurance_ids

insurance_carrier_name

string

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

location_insurance_ids

array of strings

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_insurance_ids

national_bluecard

boolean

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. Defaults to true unless otherwise specified.

specialty_ids

array of strings

List of desired specialty uuids. See all providers who specialize in the given specialties.

Cannot be used in tandem with specialty_ids_primary or specialty_primary.

specialty_ids

specialty

object

specialty_ids_primary

array of strings

List of specialty uuids. See all providers whose primary specialties are in the given specialties.

Cannot be used in tandem with specialty_ids or specialty.

specialty_ids_primary

primary_specialty

object

apply_specialty_grouping

boolean

Boolean input that enables an API search to automatically default to apply the inclusions and exclusions logic for grouping relevant specialties when using the specialty or specialty_primary parameter. Defaults to true.
For details, please read our guide on searching by specialties.

procedure_ids

array of strings

Comma separated list of desired procedure uuids. Filter to only providers who perform the given procedure.

procedure_ids

procedure

object

min_experience_index

string

≥ 0

Float input of the minimum experience index for procedures. min_experience_index=4 will only return providers that have an experience index of 4 or higher for at least one of the given procedure uuids.

Note: This parameter must be used with procedure_ids.

max_cost_index

string

≥ 0

Float input of the maximum cost index for procedures. max_cost_index=4 will only return providers that have a cost index of 4 or less for at least one of the given procedure uuids.

Note: This parameter must be used with procedure_ids.

clinical_area

string

String input that is fuzzy matched to the most relevant clinical_area.display field. Only a single clinical area will be selected.

Returns all providers with this clinical area.

clinical_area_ids

object

condition

object

condition_ids

array of strings

List of desired condition ids.
Returns all providers with a conditions.uuid field exactly matching any of the entered IDs.

(Note: Use the /conditions/ reference endpoint to identify relevant IDs)

condition_ids

treatment

object

treatment_ids

array of strings

List of desired treatment ids.
Returns all providers with a treatments.uuid field exactly matching any of the entered IDs.

(Note: Use the /treatments/ reference endpoint (docs) to identify relevant IDs)

treatment_ids

panel_ages

array of strings

List of desired Panel Ages strings. Options are:
Pediatric (0-12)
Adolescent (13-21)
Adult (22-44)
Adult (45-64)
Senior (65 and over)

Returns all providers with a panel_ages label field exactly matching any of the entered strings.

panel_ages

panel_sexes

string

Desired Panel Sexes string. Options are:

Both female and male
Primarily female
Primarily male

Returns all providers with a panel sexes label field exactly matching the entered string.

min_outcomes_index

integer

1 to 5

Accepts a single integer input between 1 and 5.

Returns providers with an aggregate Outcomes Quality score (field: performance.aggregate.quality.outcomes_index) greater than or equal to the entered parameter.

min_efficiency_index

integer

1 to 5

Accepts a single integer input between 1 and 5.

Returns providers with an aggregate Cost Efficiency score (field: performance.aggregate.cost.efficiency_index) greater than or equal to the entered parameter.

max_unit_cost_index

integer

1 to 10

Accepts a single integer input between 1 and 10.

Returns providers with an aggregate Unit Cost Index score (field: performance.aggregate.cost.unit_cost_index) less than or equal to the entered parameter.

max_ribbon_cost_score

integer

1 to 10

Accepts a single integer input between 1 and 10.

Returns providers with an aggregate Ribbon Cost Score (field: performance.aggregate.cost.ribbon_cost_score) less than or equal to the entered parameter.

Note: this search parameter is only available to customers that have purchased our Cost and Quality data.

location_organization_ids

array of strings

List of desired organization uuids. Filters to only providers who have the given organization uuid(s) listed in the provider.organizations field.

Using this parameter will also filter the provider.locations returned in order to only surface provider.locations that have the given organization(s) in the provider.locations.organizations field.

location_organization_ids

tin_ids

string

List of desired TINs.

tin_name

string

tin_legal_name

string

inclusions

object

exclusions

object

data

array of objects

required

data*

object

npi

string

The healthcare provider's 10-digit National Provider Identifier (NPI)

first_name

string

First name of the provider

middle_name

string | null

Middle name of the provider

last_name

string

Last name of the provider

age

integer | null

The estimated age of the provider

gender

string

The gender of the provider

m f

ratings_count

integer

Total number of ratings collected across different sources

ratings_avg

number | null

Average patient satisfaction rating out of 10 points across multiple sources

degrees

array of strings

Lists all degrees associated with this provider (e.g. MD, OD, PhD)

degrees

specialties

array of objects

This lists all the specialties for a given provider

specialties

object

uuid

string

A UUID uniquely identifying this specialty

taxonomy_code

string

board_specialty

string | null

board_sub_specialty

string | null

non_md_specialty

string | null

non_md_sub_specialty

string | null

provider_name

string | null

colloquial

string | null

taxonomy_1

string | null

taxonomy_2

string | null

taxonomy_3

string | null

display

string

provider_type

string

is_primary

boolean

Whether or not a specialty is a provider's primary specialty

languages

array of strings

List of confirmed languages spoken

languages

educations

array of objects

List of the schools attended by the provider

educations

object

education

object

required

type

string | null

required

year

integer | null

required

insurances

array of objects

List of insurances the provider accepts

insurances

object

uuid

string

A UUID uniquely identifying this insurance

carrier_association

string | null

carrier_brand

string | null

carrier_name

string | null

state

string | null

plan_name

string | null

plan_type

string | null

metal_level

string | null

display_name

string

network

string | null

confidence

integer | null

200Returns an ordered list of matching providers

400The search could not be completed as requested

403Trial accounts do not have access to custom provider directories