H1 Ribbon Custom Filters API
Create, edit, and delete saved custom filters for providers and locations to scope and reuse queries against the Ribbon provider and location data.
OpenAPI Specification
{
"openapi": "3.1.0",
"info": {
"title": "Ribbon Health API",
"version": "1.0.0",
"description": "An API for interacting with the data provided by Ribbon Health, including information about healthcare providers, locations, insurances, and more.\n"
},
"servers": [
{
"url": "https://api.ribbonhealth.com/v1"
}
],
"paths": {
"/custom/providers": {
"get": {
"summary": "Search Providers",
"description": "Allows you to quickly list doctors based on important search criteria.\n",
"operationId": "getCustomProviders",
"tags": [
"Providers"
],
"parameters": [
{
"name": "Pagination and Search Configuration Options",
"in": "query",
"required": false,
"description": "Options to control what data gets returned to you.",
"explode": true,
"schema": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"example": 1,
"description": "The page of the results which was returned."
},
"page_size": {
"type": "integer",
"example": 25,
"description": "How many results are in each page. \n\nNote that page_size is generally capped to 200 given the strict `max_locations * page_size <= 1000` requirement.\n"
},
"max_locations": {
"type": "integer",
"example": 5,
"description": "The maximum number of locations that will be attached to any given provider. Note that there is a strict `max_locations * page_size <= 1000` requirement.\n\nDefaults to 5.\n"
},
"fields": {
"type": "string",
"example": "locations,age",
"description": "Comma separated 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.\n\nCannot be used in tandem with `_excl_fields`.\n"
},
"_excl_fields": {
"type": "string",
"example": "locations,age",
"description": "Comma separated 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."
}
}
}
},
{
"name": "Provider Search Criteria",
"in": "query",
"required": false,
"description": "Search criteria based on aspects of the providers themselves.",
"explode": true,
"schema": {
"type": "object",
"properties": {
"npis": {
"type": "string",
"description": "Comma separated list of desired NPIs (i.e. use this to search for 5 specific doctors).\n\nA maximum of `100` NPIs can be passed in per request.\n\nNote: This parameter cannot be used in combination with most other parameters. You may combine this parameter with `fields` or `_excl_fields`. You may use geographic search parameters `location` or `address`, which will be used to populate the `distance` on the returned providers but will **not** be used to filter them. All other parameters will be ignored.\n",
"example": 1234567890
},
"name": {
"type": "string",
"description": "String input of a full, first, last, or partial name.",
"example": "Doe"
},
"provider_types": {
"type": "string",
"description": "A comma-separated list of 'types' of providers you are searching for. Provider types are higher level groupings of specialties. Here are a few key provider types:\n- Doctor\n- Nursing\n- Dental Providers\n- Optometry\n- Chiropractic Providers\n\nSee the Specialties Reference Endpoint for a list of all specialties and their provider types.\n",
"example": "Optometry"
},
"_excl_provider_types": {
"type": "string",
"description": "A comma-separated list of 'types' of providers to exclude. Excludes providers with a matching provider type.\n",
"example": "Optometry"
},
"gender": {
"type": "string",
"enum": [
"m",
"f"
],
"description": "String input of either m or f to filter to only medical providers of the inputted gender.",
"example": "m"
},
"max_age": {
"type": "integer",
"description": "Integer input (i.e. 50) to filter to only medical providers under the inputted age.",
"example": 70
},
"min_age": {
"type": "integer",
"description": "Integer input (i.e. 50) to filter to only medical providers above the inputted age.",
"example": 45
},
"language": {
"type": "string",
"description": "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.",
"example": "English"
},
"_excl_language": {
"type": "string",
"description": "Fuzzy search based on a string input (i.e. English) to exclude medical providers providers who speak / whose office staff speak the inputted language.",
"example": "English"
},
"min_rating": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"description": "Integer input (from 0 to 10) to filter to only providers above the inputted value for the ratings_avg field.",
"example": 6
}
}
}
},
{
"name": "Location Search Criteria",
"in": "query",
"required": false,
"description": "Criteria used to search for providers based on the locations at which they practice.",
"explode": true,
"schema": {
"type": "object",
"properties": {
"address": {
"type": "string",
"description": "String input of an address that will be interpreted and geocoded in real time.",
"example": "New York, NY"
},
"location_ids": {
"type": "string",
"description": "Comma separated list of desired practice location uuids. See all providers who see patients at any of the given practice locations.",
"example": "34ecc98a-e49e-49e3-84f9-b0ab2ff00495"
},
"_excl_location_ids": {
"type": "string",
"description": "Comma separated list of practice location uuids to exclude. Excludes providers who see patients at any of the given practice locations.",
"example": "34ecc98a-e49e-49e3-84f9-b0ab2ff00495"
},
"location": {
"type": "string",
"description": "Latitude/longitude pair of coordinates in lieu of a string address.",
"example": "37.7489816,-122.4802092"
},
"min_location_confidence": {
"type": "integer",
"minimum": 0,
"maximum": 5,
"description": "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.\n\nNote: 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)\n",
"example": 3
},
"min_confidence": {
"type": "integer",
"minimum": 0,
"maximum": 5,
"description": "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.",
"example": 3
},
"distance": {
"type": "integer",
"example": 10,
"description": "The proximity radius of providers returned.\n\n Note: When using `min_location_confidence` and `location_insurance_ids` parameters, limit `distance` to be less than 50 miles to ensure high quality results.\n"
},
"state": {
"type": "string",
"example": "NY",
"description": "Two-letter state abbreviation of provider locations to filter to. Note that this parameter will override `address` and `location` parameters if used together."
},
"accepting_new_patients": {
"type": "string",
"description": "Filters providers based on the `locations.accepting_new_patients` field. Accepts value `Y` to filter to providers who are likely accepting new patients.\n",
"example": "Y"
},
"ultimate_parent_id": {
"type": "string",
"description": "Exact match on the ultimate parent organization ID. Filters to only providers whose locations have the given ultimate parent ID.\n",
"example": "12345"
},
"ultimate_parent_name": {
"type": "string",
"description": "Fuzzy prefix search on the ultimate parent organization name. Returns providers whose locations have an ultimate parent name matching the given prefix.\n",
"example": "Acme Health"
}
}
}
},
{
"name": "Insurance Search Criteria",
"in": "query",
"required": false,
"description": "Criteria used to search for providers based on the insurances they accept.",
"explode": true,
"schema": {
"type": "object",
"properties": {
"insurance_ids": {
"type": "string",
"description": "Please use the location_insurance_ids parameter instead. These parameters have the same behavior and filter for insurance objects at the provider.location level.",
"example": "e527f6e3-fe42-4932-bf34-d81f1c1fd652"
},
"_excl_insurance_ids": {
"type": "string",
"description": "Comma separated list of insurance uuids to exclude. Exclude providers who accept a given insurance(s).",
"example": "e527f6e3-fe42-4932-bf34-d81f1c1fd652"
},
"insurance_carrier_name": {
"type": "string",
"description": "String input of carrier_name in order to search for all providers that take at least one plan from a given insurance carrier.\n\nFind the individual valid carrier_name values from the insurance objects returned in the Insurances Reference Endpoint.\n\nNote: This input must be an exact string match to work\n",
"example": "Aetna"
},
"location_insurance_ids": {
"type": "string",
"description": "Comma separated list of desired insurance uuids. See all provider locations that accept a given insurance(s).\n\nNote, this parameter cannot be combined with `insurance_ids` to filter on provider insurances and provider location insurances.\n",
"example": "34ecc98a-e49e-49e3-84f9-b0ab2ff00495"
},
"_excl_location_insurance_ids": {
"type": "string",
"description": "Comma separated list of insurance uuids to exclude. Excludes provider locations that accept a given insurance(s).",
"example": "34ecc98a-e49e-49e3-84f9-b0ab2ff00495"
},
"national_bluecard": {
"type": "boolean",
"example": true,
"description": "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."
}
}
}
},
{
"name": "Specialty Search Criteria",
"in": "query",
"required": false,
"description": "Criteria used to search for providers based on their specialties.",
"explode": true,
"schema": {
"type": "object",
"properties": {
"specialty_ids": {
"type": "string",
"description": "Comma separated list of desired specialty uuids. See all providers who specialize in the given specialties.\n\nCannot be used in tandem with `specialty_ids_primary`, `specialty`, or `specialty_primary`.\n",
"example": "1de33770-eb1c-47fa-ab3e-f9a4ab924d9d"
},
"_excl_specialty_ids": {
"type": "string",
"description": "Comma separated list of specialties uuids to exclude. Exclude providers who specialize in the given specialties.",
"example": "1de33770-eb1c-47fa-ab3e-f9a4ab924d9d"
},
"specialty": {
"type": "string",
"description": "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\n- gastroenterology\n- gastroenterologist\n- gastro\n- stomach doc\n- gastrooentrology\n\nThis parameter can make use of our specialty grouping logic. To learn more about this logic and/or to opt out, please use the `apply_specialty_grouping` parameter.\n\nCannot be used in tandem with `specialty_primary`, `specialty_ids`, or `specialty_ids_primary`.\n",
"example": "gastroenterology"
},
"specialty_ids_primary": {
"type": "string",
"description": "Comma separated list of specialty uuids. See all providers whose primary specialties are in the given specialties.\n\nCannot be used in tandem with `specialty_ids`, `specialty`, or `specialty_primary`.\n",
"example": "1de33770-eb1c-47fa-ab3e-f9a4ab924d9d"
},
"_excl_specialty_ids_primary": {
"type": "string",
"description": "Comma separated list of specialties uuids to exclude. Exclude providers whose primary specialties are in the given specialties.",
"example": "1de33770-eb1c-47fa-ab3e-f9a4ab924d9d"
},
"specialty_primary": {
"type": "string",
"description": "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.\n\nCannot be used in tandem with `specialty`, `specialty_ids` or `specialty_ids_primary`.\n",
"example": "gastroenterology"
},
"apply_specialty_grouping": {
"type": "boolean",
"description": "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`.\nFor details, please read [our guide on searching by specialties](https://ribbon.readme.io/docs/search-for-specialties).\n",
"example": false
}
}
}
},
{
"name": "Procedure Search Criteria",
"in": "query",
"required": false,
"description": "Criteria used to search for providers based on procedures they perform.",
"explode": true,
"schema": {
"type": "object",
"properties": {
"procedure_ids": {
"type": "string",
"description": "Comma separated list of desired procedure uuids. Filter to only providers who perform the given procedure.",
"example": "9f3fd9e8-96b0-4cc7-ab2c-8d538e9164ae"
},
"_excl_procedure_ids": {
"type": "string",
"description": "Comma separated list of procedure uuids to exclude. Exclude providers who perform the given procedure.",
"example": "9f3fd9e8-96b0-4cc7-ab2c-8d538e9164ae"
},
"procedure": {
"type": "string",
"description": "String input that is fuzzy matched to the most relevant procedure `display` field. Only a single procedure will be selected. Filter to only providers who perform the given procedure.",
"example": "MRI, thoracic spine"
},
"min_experience_index": {
"type": "float",
"description": "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.\n\nNote: This parameter must be used with `procedure_ids`.\n",
"example": 4
},
"max_cost_index": {
"type": "float",
"description": "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.\n\nNote: This parameter must be used with `procedure_ids`.\n",
"example": 4
}
}
}
},
{
"name": "Focus Area Search Criteria",
"in": "query",
"required": false,
"description": "Criteria used to search for providers based on their Focus Areas.",
"explode": true,
"schema": {
"type": "object",
"properties": {
"clinical_area": {
"type": "string",
"description": "String input that is fuzzy matched to the most relevant `clinical_area.display` field. Only a single clinical area will be selected.\n\nReturns all providers with this clinical area.\n",
"example": "Mental Health"
},
"clinical_area_ids": {
"type": "string",
"description": "Comma-separated list of desired clinical area ids.\n\nReturns all providers with a clinical area exactly matching any of the entered IDs.\n\n(Note: Use the `/clinical_areas/` reference endpoint to identify relevant IDs)\n",
"example": "a7da792c-fae3-4b46-bab7-220e0c54e376"
},
"_excl_clinical_area_ids": {
"type": "string",
"description": "Comma-separated list of clinical area ids to exclude.\n\nReturns all providers without a clinical area exactly matching any of the entered IDs.\n\n(Note: Use the `/clinical_areas/` reference endpoint to identify relevant IDs)\n",
"example": "a7da792c-fae3-4b46-bab7-220e0c54e376"
},
"condition": {
"type": "string",
"description": "String input that is fuzzy matched to the most relevant `condition.display` field. Only a single condition will be selected.\n\nReturns all providers with this condition.\n",
"example": "depression"
},
"condition_ids": {
"type": "string",
"description": "Comma-separated list of desired condition ids.\nReturns all providers with a `conditions.uuid` field exactly matching any of the entered IDs.\n\n(Note: Use the `/conditions/` reference endpoint to identify relevant IDs)\n",
"example": "fd7c10f3-fbec-482a-929b-be94a8bb3bc1"
},
"_excl_condition_ids": {
"type": "string",
"description": "Comma-separated list of condition ids to exclude.\nReturns all providers without a `conditions.uuid` field exactly matching any of the entered IDs.\n\n(Note: Use the `/conditions/` reference endpoint to identify relevant IDs)\n",
"example": "fd7c10f3-fbec-482a-929b-be94a8bb3bc1"
},
"treatment": {
"type": "string",
"description": "String input that is fuzzy matched to the most relevant `treatments.display` field. Only a single treatment will be selected.\n\nReturns all providers with this treatment.\n",
"example": "Psychological Therapy"
},
"treatment_ids": {
"type": "string",
"description": "Comma-separated list of desired treatment ids.\nReturns all providers with a `treatments.uuid` field exactly matching any of the entered IDs.\n\n(Note: Use the /treatments/ reference endpoint (docs) to identify relevant IDs)\n",
"example": "11016779-e286-4b17-bd45-2d78660a9f28"
},
"_excl_treatment_ids": {
"type": "string",
"description": "Comma-separated list of treatment ids to exclude.\nReturns all providers without a `treatments.uuid` field exactly matching any of the entered IDs.\n\n(Note: Use the /treatments/ reference endpoint (docs) to identify relevant IDs)\n",
"example": "11016779-e286-4b17-bd45-2d78660a9f28"
},
"panel_ages": {
"type": "string",
"description": "Comma-separated list of desired Panel Ages strings. Options are:\n `Pediatric (0-12)`\n `Adolescent (13-21)`\n `Adult (22-44)`\n `Adult (45-64)`\n `Senior (65 and over)`\n\nReturns all providers with a `panel_ages` label field exactly matching any of the entered strings.\n",
"example": "Pediatric (0-12),Adolescent (13-21)"
},
"_excl_panel_ages": {
"type": "string",
"description": "Comma-separated list of Panel Ages strings to exclude. Options are:\n `Pediatric (0-12)`\n `Adolescent (13-21)`\n `Adult (22-44)`\n `Adult (45-64)`\n `Senior (65 and over)`\n\nReturns all providers without a `panel_ages` label field exactly matching any of the entered strings.\n",
"example": "Pediatric (0-12),Adolescent (13-21)"
},
"panel_sexes": {
"type": "string",
"description": "Desired Panel Sexes string. Options are:\n\n `Both female and male`\n `Primarily female`\n `Primarily male`\n\nReturns all providers with a panel sexes label field exactly matching the entered string.\n",
"example": "Primarily female"
}
}
}
},
{
"name": "Cost and Quality Criteria",
"in": "query",
"required": false,
"description": "Criteria used to search for providers based on Cost and Quality scores.",
"explode": true,
"schema": {
"type": "object",
"properties": {
"min_outcomes_index": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"description": "Accepts a single integer input between 1 and 5.\n\nReturns providers with an aggregate Outcomes Quality score (field: `performance.aggregate.quality.outcomes_index`) greater than or equal to the entered parameter.\n"
},
"min_efficiency_index": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"description": "Accepts a single integer input between 1 and 5.\n\nReturns providers with an aggregate Cost Efficiency score (field: `performance.aggregate.cost.efficiency_index`) greater than or equal to the entered parameter.\n"
},
"max_unit_cost_index": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "Accepts a single integer input between 1 and 10.\n\nReturns providers with an aggregate Unit Cost Index score (field: `performance.aggregate.cost.unit_cost_index`) less than or equal to the entered parameter.\n"
},
"max_ribbon_cost_score": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "Accepts a single integer input between 1 and 10.\n\nReturns providers with an aggregate Ribbon Cost Score (field: `performance.aggregate.cost.ribbon_cost_score`) less than or equal to the entered parameter.\n\nNote: this search parameter is only available to customers that have purchased our Cost and Quality data.\n"
}
}
}
},
{
"name": "Organization Search Criteria",
"in": "query",
"required": false,
"description": "Criteria used to search for providers based on the organizations they belong to.",
"explode": true,
"schema": {
"type": "object",
"properties": {
"location_organization_ids": {
"type": "string",
"description": "Comma separated list of desired organization uuids. Filters to only providers who have the given organization uuid(s) listed in the `provider.organizations` field.\n\nUsing 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.\n",
"example": "497a1ac1-52cc-43a9-b796-844dabde10fc"
},
"_excl_location_organization_ids": {
"type": "string",
"description": "Comma separated list of organization uuids to exclude. Excludes providers who have the given organization uuid(s) listed in the `provider.organizations` field.",
"example": "497a1ac1-52cc-43a9-b796-844dabde10fc"
}
}
}
},
{
"name": "TINs Search Criteria",
"in": "query",
"required": false,
"description": "Criteria used to search for providers based on the TINs they are associated with.",
"explode": true,
"schema": {
"type": "object",
"properties": {
"tin_ids": {
"type": "string",
"description": "Comma separated list of desired TINs. Filters to only providers who have the given TINs listed in the `provider.location` field.\nNote: This parameter cannot be used in combination with any other TINs related parameters. All other TINs related parameters will be ignored.\n"
},
"tin_name": {
"type": "string",
"description": "String input that is fuzzy matched against the `tins.name` field. Filters to only providers who have the given TINs name listed in the `provider.location` field."
},
"tin_legal_name": {
"type": "string",
"description": "String input that is fuzzy matched against the `tins.legal_name` field. Filters to only providers who have the given TINs legal name listed in the `provider.location` field."
}
}
}
}
],
"responses": {
"200": {
"description": "Returns an ordered list of matching providers",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"parameters",
"data"
],
"properties": {
"parameters": {
"allOf": [
{
"type": "object",
"properties": {
"total_count": {
"type": "integer",
"example": 141,
"description": "The total number of results matched, across all pages."
},
"sort_by": {
"type": "string",
"example": "distance",
"description": "The main criteria used to sort results in the record set."
},
"geo": {
"type": "object",
"properties": {
"latitude": {
"type": "number",
"example": 40.7351327,
"description": "The latitude the search was focused on."
},
"longitude": {
"type": "number",
"example": -73.9881657,
"description": "The longitude the search was focused on."
}
}
}
}
},
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"example": 1,
"description": "The page of the results which was returned."
},
"page_size": {
"type": "integer",
"example": 25,
"description": "How many results are in each page."
},
"max_locations": {
"type": "integer",
"example": 5,
"description": "The maximum number of locations attached to any given provider. Defaults to 5 (not shown if unspecified)."
},
"fields": {
"type": "array",
"items": {
"type": "string",
"example": "locations"
},
"example"
# --- truncated at 32 KB (402 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/h1/refs/heads/main/openapi/ribbon-health-api-openapi.json