--- updatedAt: 2026-06-05T13:06:03.000Z agentTools: projectIndex: https://ribbon.readme.io/llms.txt --- # Search Providers Allows you to quickly list doctors based on important search criteria. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "H1's API", "version": "1.0.0", "description": "An API for interacting with the data provided by Ribbon Health, including information about healthcare providers,\nlocations, insurances, and more.\n\n## Price Transparency v2\n\nLocation-first negotiated rate endpoints live under `/v2/*` (separate from legacy\n`/v1/pricing/*`). Use them to:\n\n1. Look up procedures, care clusters, and carriers (`GET /v2/procedures`,\n `/v2/care-clusters`, `/v2/carriers`)\n2. Get prices for a known location (`GET /v2/locations/{location_id}/pricing/...`)\n3. Shop by geography (`GET /v2/pricing/locations/...`)\n\n**Key differences from v1:** prices are location-scoped (not provider-first);\ncarriers use string business ids (not v1 carrier UUIDs); every v2 response uses\nthe same envelope (`parameters`, `total_count`, `page`, `page_size`, `data`);\ngeo search requires an explicit `address` or `lat`+`lng` (no silent default).\n\nSee the **Price Transparency v2** tag for full endpoint reference.\n" }, "servers": [ { "url": "https://api.ribbonhealth.com" } ], "tags": [ { "name": "Providers", "description": "Search and manage provider data, keyed by NPI." }, { "name": "Price Transparency v2", "description": "Location-first negotiated rates under `/v2/*`. Prefer these endpoints for new\nintegrations. Carrier ids come from `GET /v2/carriers` and are not interchangeable\nwith v1 pricing carrier UUIDs. Provider-scoped v2 routes are not live yet.\n" } ], "paths": { "/v1/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_score.outcomes_index`) greater than or equal to the entered parameter.\n\nRequires access to performance data; requests without it return a 400.\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_score.efficiency_index`) greater than or equal to the entered parameter.\n\nRequires access to performance data; requests without it return a 400.\n" }, "efficiency_score": { "type": "number", "minimum": 0, "maximum": 100, "description": "Accepts a single number input between 0 and 100.\n\nReturns providers with a raw Cost Efficiency score (field: `performance_score.efficiency_score`) greater than or equal to the entered parameter.\n\nRequires access to performance data; requests without it return a 400.\n" }, "quality_score": { "type": "number", "minimum": 0, "maximum": 100, "description": "Accepts a single number input between 0 and 100.\n\nReturns providers with a raw Quality score (field: `performance_score.quality_score`) greater than or equal to the entered parameter.\n\nRequires access to performance data; requests without it return a 400.\n" }, "performance_score": { "type": "number", "minimum": 0, "maximum": 100, "description": "Accepts a single number input between 0 and 100.\n\nReturns providers with an overall Performance score (field: `performance_score.total_score`) greater than or equal to the entered parameter.\n\nRequires access to performance data; requests without it return a 400.\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": [ "locations", "age" ], "description": "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": "array", "items": { "type": "string", "example": "locations" }, "example": [ "locations", "age" ], "description": "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." } } }, { "type": "object", "properties": { "npis": { "type": "array", "items": { "type": "string", "example": 1234567890 }, "description": "List of desired NPIs (i.e. use this to search for 5 specific doctors).\n\nNote: This parameter cannot be used in combination with any other parameters. 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": "array", "items": { "type": "string", "example": "Optometry" }, "description": "The 'types' of providers you searched 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" ] }, "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": "object", "properties": { "results": { "type": "array", "items": { "type": "string", "example": "french" }, "description": "The languages that matched the given `language` parameter" }, "value": { "type": "string", "example": "English" }, "description": "The given input to the `language` parameter" } }, "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 } } }, { "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": "array", "items": { "type": "string", "format": "uuid", "example": "34ecc98a-e49e-49e3-84f9-b0ab2ff00495" }, "description": "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" ] }, "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." } } }, { "type": "object", "properties": { "insurance_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "e527f6e3-fe42-4932-bf34-d81f1c1fd652" }, "description": "List of desired insurance uuids. See all 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": "array", "items": { "type": "string", "format": "uuid", "example": "34ecc98a-e49e-49e3-84f9-b0ab2ff00495" }, "description": "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" ] }, "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." } } }, { "type": "object", "properties": { "specialty_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "1de33770-eb1c-47fa-ab3e-f9a4ab924d9d" }, "description": "List of desired specialty uuids. See all providers who specialize in the given specialties.\n\nCannot be used in tandem with `specialty_ids_primary` or `specialty_primary`.\n", "example": [ "1de33770-eb1c-47fa-ab3e-f9a4ab924d9d" ] }, "specialty": { "$ref": "#/paths/~1v1~1custom~1specialties~1%7Bspecialty_uuid%7D/get/responses/200/content/application~1json/schema" }, "specialty_ids_primary": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "1de33770-eb1c-47fa-ab3e-f9a4ab924d9d" }, "description": "List of specialty uuids. See all providers whose primary specialties are in the given specialties.\n\nCannot be used in tandem with `specialty_ids` or `specialty`.\n", "example": [ "1de33770-eb1c-47fa-ab3e-f9a4ab924d9d" ] }, "primary_specialty": { "$ref": "#/paths/~1v1~1custom~1specialties~1%7Bspecialty_uuid%7D/get/responses/200/content/application~1json/schema" }, "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 } } }, { "type": "object", "properties": { "procedure_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "9f3fd9e8-96b0-4cc7-ab2c-8d538e9164ae" }, "description": "Comma separated list of desired procedure uuids. Filter to only providers who perform the given procedure.", "example": [ "9f3fd9e8-96b0-4cc7-ab2c-8d538e9164ae" ] }, "procedure": { "$ref": "#/paths/~1v1~1procedures~1%7Bprocedure_uuid%7D/get/responses/200/content/application~1json/schema" }, "min_experience_index": { "type": "float", "minimum": 0, "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", "minimum": 0, "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 } } }, { "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": { "$ref": "#/paths/~1v1~1custom~1clinical_areas~1%7Bclinical_area_uuid%7D/get/responses/200/content/application~1json/schema" }, "condition": { "$ref": "#/paths/~1v1~1custom~1conditions~1%7Bcondition_uuid%7D/get/responses/200/content/application~1json/schema" }, "condition_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "fd7c10f3-fbec-482a-929b-be94a8bb3bc1" }, "description": "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" ] }, "treatment": { "$ref": "#/paths/~1v1~1custom~1treatments~1%7Btreatment_uuid%7D/get/responses/200/content/application~1json/schema" }, "treatment_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "11016779-e286-4b17-bd45-2d78660a9f28" }, "description": "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" ] }, "panel_ages": { "type": "array", "items": { "type": "string", "example": [ "Pediatric (0-12)" ] }, "description": "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)" ] }, "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" } } }, { "$ref": "#/paths/~1v1~1custom~1providers/get/parameters/7/schema" }, { "type": "object", "properties": { "location_organization_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "497a1ac1-52cc-43a9-b796-844dabde10fc" }, "description": "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" ] } } }, { "type": "object", "properties": { "tin_ids": { "type": "string", "description": "List of desired TINs." }, "tin_name": { "type": "string" }, "tin_legal_name": { "type": "string" } } }, { "type": "object", "properties": { "inclusions": { "type": "object", "properties": { "specialty_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "ec41ff31-571d-422e-a8b5-806bed6a6c04" }, "example": [ "ec41ff31-571d-422e-a8b5-806bed6a6c04" ], "description": "A list of specialty IDs included in the search based on the fuzzy-matched `specialty` parameter." }, "specialty_ids_primary": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "ec41ff31-571d-422e-a8b5-806bed6a6c04" }, "example": [ "ec41ff31-571d-422e-a8b5-806bed6a6c04" ], "description": "A list of primary specialty IDs included in the search based on the fuzzy-matched `specialty_primary` parameter." } } } } }, { "type": "object", "properties": { "exclusions": { "type": "object", "properties": { "provider_types": { "type": "array", "items": { "type": "string", "example": "Optometry" }, "description": "List of 'types' of providers excluded. Excludes any providers with a matching provider type.", "example": [ "Optometry" ] }, "insurance_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "e527f6e3-fe42-4932-bf34-d81f1c1fd652" }, "description": "List of insurance uuids excluded. Excludes any providers who accept a given insurance(s).", "example": [ "e527f6e3-fe42-4932-bf34-d81f1c1fd652" ] }, "location_insurance_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "34ecc98a-e49e-49e3-84f9-b0ab2ff00495" }, "description": "List of insurance uuids excluded. Excludes any provider locations that accept a given insurance(s).", "example": [ "34ecc98a-e49e-49e3-84f9-b0ab2ff00495" ] }, "location_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "34ecc98a-e49e-49e3-84f9-b0ab2ff00495" }, "description": "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_organization_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "497a1ac1-52cc-43a9-b796-844dabde10fc" }, "description": "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" ] }, "specialty_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "ec41ff31-571d-422e-a8b5-806bed6a6c04" }, "example": [ "ec41ff31-571d-422e-a8b5-806bed6a6c04" ], "description": "A list of specialty IDs excluded from the search. This can be the result of using `_excl_specialty_ids` or exclusions based on the fuzzy-matched `specialty` parameter." }, "specialty_ids_primary": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "ec41ff31-571d-422e-a8b5-806bed6a6c04" }, "example": [ "ec41ff31-571d-422e-a8b5-806bed6a6c04" ], "description": "A list of primary specialty IDs excluded from the search. This can be the result of using `_excl_specialty_ids_primary` or exclusions based on the fuzzy-matched `specialty_primary` parameter." }, "procedure_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "9f3fd9e8-96b0-4cc7-ab2c-8d538e9164ae" }, "description": "Comma separated list of procedure uuids to exclude. Exclude providers who perform the given procedure.", "example": [ "9f3fd9e8-96b0-4cc7-ab2c-8d538e9164ae" ] }, "language": { "type": "object", "properties": { "value": { "type": "string", "example": "english" }, "results": { "type": "array", "items": { "type": "string", "example": "english" }, "example": [ "english" ] } }, "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." } } } } } ] }, "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/paths/~1v1~1custom~1providers~1%7Bnpi%7D/get/responses/200/content/application~1json/schema" }, { "type": "object", "properties": { "locations": { "type": "array", "items": { "allOf": [ { "$ref": "#/paths/~1v1~1custom~1locations/get/responses/200/content/application~1json/schema/properties/data/items" }, { "type": "object", "properties": { "accepting_new_patients": { "type": [ "string", "null" ], "example": "Y", "description": "Indicates whether the provider is likely accepting new patients at this location" } } } ] }, "description": "List of all locations this provider is known to practice at including any known phone numbers at these locations" } } } ] } } } } } } }, "400": { "description": "The search could not be completed as requested", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v2~1carriers/get/responses/400/content/application~1json/schema" } } } }, "403": { "description": "Trial accounts do not have access to custom provider directories", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v2~1carriers/get/responses/403/content/application~1json/schema" } } } } } } }, "/v1/custom/locations": { "get": { "summary": "Search Locations", "description": "Allows you to search for different service locations, including specific location types.\n", "operationId": "getCustomLocations", "tags": [ "Locations" ], "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." }, "fields": { "type": "string", "example": "name,address", "description": "Comma separated list of fields within the location object to return. Can be used to greatly reduce the size of the response by requesting only data you intend to use.\nCannot be used in tandem with `_excl_fields`\n" }, "_excl_fields": { "type": "string", "example": "phone_numbers,insurances", "description": "Comma separated list of fields within the location 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": "Location Search Options", "in": "query", "required": false, "description": "Search options based on aspects of the location objects.", "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" }, "name": { "type": "string", "description": "String input for a 'fuzzy' search on location name.", "example": "Citymd Urgent Care" }, "distance": { "type": "integer", "example": 10, "description": "The proximity radius of locations returned.\n" }, "location_types": { "type": "string", "description": "Comma separated list of values that filter to what type of facilities to show. We categorize locations into 36 types. Clients can add their own locations with unique location_types, and they will also be included in the search.\nSee the Location Types Reference Endpoint for a list of all location types.\n", "example": "Urgent Care" }, "_excl_location_types": { "type": "string", "description": "Comma separated list of the 'types' of locations to exclude. Excludes locations with a matching location type.\n", "example": "Urgent Care" }, "location": { "type": "string", "description": "Latitude/longitude pair of coordinates in lieu of a string address.", "example": "37.7489816,-122.4802092" }, "location_ids": { "type": "string", "description": "Comma separated list of desired practice location uuids.", "example": "48d4eb27-d82b-4ea4-8ad0-4bcb2c46a960" }, "_excl_location_ids": { "type": "string", "description": "Comma separated list of practice location uuids to exclude.", "example": "48d4eb27-d82b-4ea4-8ad0-4bcb2c46a960" }, "insurance_ids": { "type": "string", "description": "Comma separated list of desired insurance uuids. See all locations that accept a given insurance(s).", "example": "24617022-92b3-4b9f-af1c-4df21ad6fb6f" }, "_excl_insurance_ids": { "type": "string", "description": "Comma separated list of insurance uuids to exclude. Exclude locations that accept a given insurance(s).", "example": "24617022-92b3-4b9f-af1c-4df21ad6fb6f" }, "insurance_carrier_name": { "type": "string", "description": "String input of carrier_name in order to search for all locations that take at least one plan from a given insurance carrier.\nFind the individual valid carrier_name values from the insurance objects returned in the Insurances Reference Endpoint.\nNote: This input must be an exact string match to work\n", "example": "Aetna" }, "min_confidence": { "type": "integer", "minimum": 0, "maximum": 5, "description": "Integer input (0-5) of the minimum confidence threshold for returned locations. min_location_confidence=4 will only display locations that have a confidence 4 or higher.\n" }, "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." }, "ultimate_parent_id": { "type": "string", "description": "Exact match on the ultimate parent organization ID. Filters to only locations that 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 locations with an ultimate parent name matching the given prefix.\n", "example": "Acme Health" }, "tier": { "type": "integer", "enum": [ 1, 2, 3 ], "example": 1, "description": "Filter to locations with the given quality tier derived from the linked organization's `hco_research` flags.\n\n * `1` - High-confidence facility\n * `2` - Medium-confidence facility\n * `3` - Low-confidence facility\n\nOnly `1`, `2`, or `3` are accepted; any other value returns a 400. Locations whose `tier` is `null` in the index are excluded from the result set when this parameter is set.\n" } } } }, { "name": "Organization Search Criteria", "in": "query", "required": false, "description": "Criteria used to search for locations based on the organizations they belong to.", "explode": true, "schema": { "type": "object", "properties": { "organization_ids": { "type": "string", "description": "Comma separated list of desired organization uuids. Filters to only locations that are affiliated with the given organization uuid(s).\n", "example": "86722ebb-1dd1-4846-a1a9-a7a9e36c944d" }, "_excl_organization_ids": { "type": "string", "description": "Comma separated list of organization uuids to exclude. Excludes locations that are affiliated with the given organization uuid(s).", "example": "86722ebb-1dd1-4846-a1a9-a7a9e36c944d" } } } }, { "name": "Focus Area Search Criteria", "in": "query", "required": false, "description": "Criteria used to search for locations 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.\nReturns all location with this clinical area.\n", "example": "CT" }, "clinical_area_ids": { "type": "string", "description": "Comma-separated list of desired clinical area ids.\nReturns all locations with a clinical area exactly matching any of the entered IDs.\n(Note: Use the `/clinical_areas/` reference endpoint to identify relevant IDs)\n", "example": "4c03ddb4-f6c0-4574-a51e-508f83c43d69" }, "_excl_clinical_area_ids": { "type": "string", "description": "Comma-separated list of clinical area ids to exclude.\nReturns all locations without a clinical area exactly matching any of the entered IDs.\n(Note: Use the `/clinical_areas/` reference endpoint to identify relevant IDs)\n", "example": "4c03ddb4-f6c0-4574-a51e-508f83c43d69" }, "treatment": { "type": "string", "description": "String input that is fuzzy matched to the most relevant `treatments.display` field. Only a single treatment will be selected.\nReturns all locations with this treatment.\n", "example": "Neck X-ray" }, "treatment_ids": { "type": "string", "description": "Comma-separated list of desired treatment ids.\nReturns all locations with a `treatments.uuid` field exactly matching any of the entered IDs.\n(Note: Use the /treatments/ reference endpoint (docs) to identify relevant IDs)\n", "example": "e3079513-bf55-41cc-87c6-f7ff5f923085" }, "_excl_treatment_ids": { "type": "string", "description": "Comma-separated list of treatment ids to exclude.\nReturns all locations without a `treatments.uuid` field exactly matching any of the entered IDs.\n(Note: Use the /treatments/ reference endpoint (docs) to identify relevant IDs)\n", "example": "e3079513-bf55-41cc-87c6-f7ff5f923085" } } } }, { "name": "TINs Search Criteria", "in": "query", "required": false, "description": "Criteria used to search for locations 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 locations that are affiliated with the given TINs.\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 locations that are affiliated with the given TINs name." }, "tin_legal_name": { "type": "string", "description": "String input that is fuzzy matched against the `tins.legal_name` field. Filters to only locations that are affiliated with the given TINs legal name." } } } } ], "responses": { "200": { "description": "Returns an ordered list of matching locations", "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." }, "fields": { "type": "array", "items": { "type": "string", "example": "locations" }, "example": [ "locations", "age" ], "description": "List of fields within the location 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": "array", "items": { "type": "string", "example": "locations" }, "example": [ "locations", "age" ], "description": "List of fields within the location 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." } } }, { "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" }, "name": { "type": "string", "description": "String input for a fuzzy search on location name.", "example": "Citymd Urgent Care" }, "distance": { "type": "integer", "example": 10, "description": "The proximity radius of locations returned.\n" }, "location_types": { "type": "array", "items": { "type": "string", "example": "Urgent Care" }, "description": "List of values that filter to what type of facilities to show. We categorize locations into 34 types. Clients can add their own locations with unique location_types, and they will also be included in the search.\nSee the Location Types Reference Endpoint for a list of all location types.\n", "example": [ "Urgent Care" ] }, "_excl_location_types": { "type": "array", "items": { "type": "string", "example": "Urgent Care" }, "description": "List of the 'types' of locations to exclude. Excludes locations with a matching location type.\n", "example": [ "Urgent Care" ] }, "insurance_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "e527f6e3-fe42-4932-bf34-d81f1c1fd652" }, "description": "List of desired insurance uuids. See all locations that accept a given insurance(s).", "example": [ "e527f6e3-fe42-4932-bf34-d81f1c1fd652" ] }, "_excl_insurance_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "e527f6e3-fe42-4932-bf34-d81f1c1fd652" }, "description": "List of insurance uuids to exclude. Exclude locations that 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 locations that take at least one plan from a given insurance carrier.\nFind the individual valid carrier_name values from the insurance objects returned in the Insurances Reference Endpoint.\nNote: This input must be an exact string match to work\n", "example": "Aetna" }, "min_confidence": { "type": "integer", "minimum": 0, "maximum": 5, "description": "Integer input (0-5) of the minimum confidence threshold for returned locations. min_location_confidence=4 will only display locations that have a confidence 4 or higher.\n" }, "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." }, "tier": { "type": "integer", "enum": [ 1, 2, 3 ], "example": 1, "description": "Filter to locations with the given quality tier (`1` = high, `2` = medium, `3` = low). Locations with `tier = null` are excluded when this filter is set.\n" } } }, { "type": "object", "properties": { "organization_ids": { "type": "array", "items": { "type": "string", "example": "86722ebb-1dd1-4846-a1a9-a7a9e36c944d" }, "description": "Comma separated list of desired organization uuids. Filters to only locations that are affiliated with the given organization uuid(s).\n", "example": [ "86722ebb-1dd1-4846-a1a9-a7a9e36c944d" ] }, "_excl_organization_ids": { "type": "array", "items": { "type": "string", "example": "497a1ac1-52cc-43a9-b796-844dabde10fc" }, "description": "Comma separated list of organization uuids to exclude. Excludes locations that are affiliated with the given organization uuid(s).", "example": [ "86722ebb-1dd1-4846-a1a9-a7a9e36c944d" ] } } }, { "type": "object", "properties": { "clinical_area": { "$ref": "#/paths/~1v1~1custom~1clinical_areas~1%7Bclinical_area_uuid%7D/get/responses/200/content/application~1json/schema" }, "clinical_area_ids": { "type": "array", "items": { "type": "string", "example": "4c03ddb4-f6c0-4574-a51e-508f83c43d69" }, "description": "List of desired clinical area ids.\nReturns all locations with a clinical area exactly matching any of the entered IDs.\n(Note: Use the `/clinical_areas/` reference endpoint to identify relevant IDs)\n", "example": [ "4c03ddb4-f6c0-4574-a51e-508f83c43d69" ] }, "treatment": { "$ref": "#/paths/~1v1~1custom~1treatments~1%7Btreatment_uuid%7D/get/responses/200/content/application~1json/schema" }, "treatment_ids": { "type": "array", "items": { "type": "string", "example": "e3079513-bf55-41cc-87c6-f7ff5f923085" }, "description": "List of desired treatment ids.\nReturns all providers with a `treatments.uuid` field exactly matching any of the entered IDs.\n(Note: Use the /treatments/ reference endpoint (docs) to identify relevant IDs)\n", "example": [ "e3079513-bf55-41cc-87c6-f7ff5f923085" ] } } }, { "type": "object", "properties": { "tin_ids": { "type": "string", "description": "List of desired TINs." }, "tin_name": { "type": "string" }, "tin_legal_name": { "type": "string" } } } ] }, "data": { "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "distance": { "type": "number", "example": 0.4, "description": "This location's distance from the center of a geographic search, in miles." } } }, { "$ref": "#/paths/~1v1~1custom~1locations~1%7Blocation_uuid%7D/get/responses/200/content/application~1json/schema" } ] } } } } } } }, "400": { "description": "The search could not be completed as requested", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v2~1carriers/get/responses/400/content/application~1json/schema" } } } }, "403": { "description": "Account does not have access to custom locations directory", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v2~1carriers/get/responses/403/content/application~1json/schema" } } } } } } }, "/v2/carriers": { "get": { "summary": "List Carriers (v2)", "description": "List carriers available in the Price Transparency v2 pricing data set.\n\nUse this to discover valid `carrier_id` values for pricing filters.\n\n#### Important\nThese identifiers are **not** the same as v1 [`/v1/pricing/carriers`](./getpricingcarriers)\nUUIDs. Always resolve carriers through this endpoint (or a curated customer\nmapping) when working with v2.\n", "operationId": "getV2Carriers", "tags": [ "Price Transparency v2" ], "parameters": [ { "name": "carrier_id", "in": "query", "required": false, "description": "Exact match on carrier business id.", "schema": { "type": "string", "example": "78110" } }, { "name": "carrier_name", "in": "query", "required": false, "description": "Match on carrier display name. Case-insensitive substring on\n`/v2/carriers`; case-insensitive exact match on DB-backed pricing endpoints;\ncase-sensitive exact match on Elasticsearch search endpoints.\n", "schema": { "type": "string", "example": "Aetna" } }, { "name": "page", "in": "query", "required": false, "description": "Page of results to return. Values below `1` are treated as `1`.\n", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Number of results per page. Hard-capped at **100**.\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 20 } } ], "responses": { "200": { "description": "Matching carriers.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "Standard response envelope for all Price Transparency v2 endpoints.\nPagination fields are always present; `parameters` echoes the non-null filters\nthat were applied (pagination keys are omitted from the echo).\n", "required": [ "parameters", "total_count", "page", "page_size", "data" ], "properties": { "parameters": { "type": "object", "additionalProperties": true, "description": "Echo of non-null request filters (pagination omitted).", "example": { "code": "27447", "code_scheme": "CPT" } }, "total_count": { "type": "integer", "description": "Total matching rows across all pages.", "example": 1 }, "page": { "type": "integer", "description": "Current page number.", "example": 1 }, "page_size": { "type": "integer", "description": "Page size used for this response.", "example": 20 }, "data": { "type": "array", "description": "Records for the current page.", "items": {} } } }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "An insurance carrier in the Price Transparency v2 data set.\nUse `carrier_id` as the filter value on pricing endpoints.\n", "required": [ "carrier_id", "name" ], "properties": { "carrier_id": { "type": "string", "description": "Business id used in all v2 pricing filters.", "example": "78110" }, "name": { "type": "string", "description": "Display name.", "example": "Aetna" } } }, "example": [ { "carrier_id": "78110", "name": "Aetna" } ] } } } ] }, "example": { "parameters": { "carrier_name": "aetna" }, "total_count": 1, "page": 1, "page_size": 20, "data": [ { "carrier_id": "78110", "name": "Aetna" } ] } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "type": "object", "description": "An error returned from the API", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "status", "code", "message" ], "properties": { "status": { "type": "integer", "description": "The HTTP error code associated with this error", "example": 400 }, "code": { "type": "string", "enum": [ "invalid_query_params", "bad_request" ] }, "message": { "type": [ "object", "string" ], "description": "An object representing what exactly went wrong. The keys available in this object vary with the type of error returned.\n", "example": { "query": { "_schema": [ "parameters 'npis' and 'location_ids' cannot be used together" ] } } } } } } } } } }, "403": { "description": "The caller does not have Price Transparency access.", "content": { "application/json": { "schema": { "type": "object", "description": "You are not allow to make this request", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "status", "code", "message" ], "properties": { "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "enum": [ "permission_denied" ] }, "message": { "type": "string", "example": "a trial account does not have access to this functionality" } } } } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [ { "BearerAuth": [] } ] } ```