# Table of Contents - [Getting Started](#getting-started) - [Authentication](#authentication) - [Ribbon Directory](#ribbon-directory) - [Confidence Scores](#confidence-scores) - [Specialties](#specialties) - [Networks](#networks) - [Ribbon Products](#ribbon-products) - [Location Search](#location-search) - [Procedure-Level Cost & Experience](#procedure-level-cost-experience) - [Procedures](#procedures) - [Introduction](#introduction) - [Eligibility](#eligibility) - [Search for Procedures](#search-for-procedures) - [Search for In-Network Providers](#search-for-in-network-providers) - [Provider Search Basics](#provider-search-basics) - [Location Types](#location-types) - [Search by Organization (Locations)](#search-by-organization-locations-) - [NPI (National Provider Identifier)](#npi-national-provider-identifier-) - [Location Search Basics](#location-search-basics) - [Cost & Quality](#cost-quality) - [Search for Location Types](#search-for-location-types) - [Find a Specific Provider](#find-a-specific-provider) - [TINs](#tins) - [Focus Areas](#focus-areas) - [Cost & Quality Search](#cost-quality-search) - [Organizations](#organizations) - [Search by Organization (Providers)](#search-by-organization-providers-) - [Patient Satisfaction Rating](#patient-satisfaction-rating) - [Search for Specialties](#search-for-specialties) - [Provider Search](#provider-search) - [Aggregate Cost/Quality Scores](#aggregate-cost-quality-scores) - [User Dropdown](#user-dropdown) - [Filtering/Ranking](#filtering-ranking) - [Network Data](#network-data) - [Include/Exclude Fields from API Response](#include-exclude-fields-from-api-response) - [Rate Limits](#rate-limits) - [Network Mapping](#network-mapping) - [Latency](#latency) --- # Getting Started Welcome to the Ribbon API! [](#welcome-to-the-ribbon-api) ------------------------------------------------------------- Whether you're new here or building on an existing implementation, we're excited to help you get started! We built Ribbon to simplify healthcare decisions. Ribbon provides the most accurate and comprehensive data on providers, plans, and healthcare costs. Our goal is to enable your team to build a seamless and effective care navigation solution for your users. To this goal, we have built extensive documentation to help you better understand Ribbon's data and API. The documentation is split into two sections: [Guides](/docs) and [API Reference](/reference/getcustomproviders) . Below, we will go through how your team should use both of these sections. If you haven't gotten an API key yet, please sign up at [https://www.ribbonhealth.com/try-now/](https://www.ribbonhealth.com/try-now/) Guides [](#guides) ---------------------- Ribbon's Guides provide a comprehensive overview of our data and help you understand how to build complete workflows using individual API endpoints. These guides are split up into a few sections: 1. **[Ribbon Data](/docs/ribbon-directory) :** Interpreting Ribbon data and our different product modules 2. **[Workflow Guides](/docs/introduction) :** Common workflows/use cases for using Ribbon's API 3. **[API Information](/docs/latency) :** Limitations and optimizations of Ribbon's API API Reference [](#api-reference) ------------------------------------ Want to understand how to structure individual API requests? The API Reference section provides a detailed deep dive into implementing specific endpoints within Ribbon's API. If you're currently building an integration and want to understand how to apply the right parameters to a [search request](/reference/getcustomproviders) or use the [reference endpoints](/reference/getinsurances) , this is for you! This section is split up by endpoint: 1. **Providers:** `` 2. **Filters:** `` 3. **Locations:** `` 4. **Reference Endpoints:** Using the reference endpoints (across `/insurances`, `/specialties`, `/location_types`, `/procedures`) 5. **Focus Areas:** `` 6. **Organizations:** `` 7. **Price Transparency:** `` 8. **Eligibility:** `` Updated 9 months ago * * * --- # Authentication The Ribbon API uses an API Key to authenticate requests. Authentication is performed by passing the token as an HTTP header in the Bearer Authentication scheme `Authorization: Bearer {customer_token}`. > 🚧 > > Make sure to keep this API Key secure! > > > -------------------------------------------- > > Do not share your API Key in publicly accessible areas, such as Github, client-side code, or internal communication tools Updated over 1 year ago * * * --- # Ribbon Directory ### What is it? [](#what-is-it) The Ribbon API displays information about every provider in the United States, ranging from the basics like location and contact information to granular detailed information like insurance plans accepted and cost/quality scores. Our API also surfaces information about the locations at which healthcare services are delivered. This allows your team to build new applications leveraging the data to solve a variety of use cases, including but not limited to: * Surfacing providers and locations based on relevant search criteria * Finding specific providers and the locations they practice at * Verifying a provider’s accepted insurance plans in real-time ### Why is it useful? [](#why-is-it-useful) Ribbon’s directory data connects to our other data sources, including ‘specialties’, ‘focus areas’, ‘cost and quality’, and more. This allows you to direct patients to care with as narrow or broad a scope as needed for your use case. Ribbon’s [confidence scoring](/docs/confidence-scores) can be used to ensure that you’re sending patients to providers that you’re confident can provide them with the care that they need. ### Methodology [](#methodology) Ribbon compiles provider and location data from a variety of sources, including claims, network/hospital directories, data vendors, and public sources. Because healthcare data is often messy and inaccurate, Ribbon doesn’t just trust one source. Rather, we use data from different relevant sources to verify/validate information about a provider at every level - ranging from how we assign name/specialty to our confidence that they practice at a particular address and can be reached at a specific phone number. Updated 10 months ago * * * * [Provider Search Guides](https://ribbon.readme.io/v2.2/docs/provider-search) * [Location Search Guides](https://ribbon.readme.io/v2.2/docs/location-search) * [Providers Endpoint Documentation](https://ribbon.readme.io/v2.2/reference/getcustomproviders) * [Locations Endpoint Documentation](https://ribbon.readme.io/v2.2/reference/getcustomlocations) --- # Confidence Scores ### What is a confidence score? [](#what-is-a-confidence-score) A confidence score is a number from one (1) to five (5) that represents the likelihood that a given provider’s contact information (i.e., address, phone number) is accurate. It is based on the output of a Machine Learning (ML) model that is designed to predict accuracy. ### Why does Ribbon use confidence scores? [](#why-does-ribbon-use-confidence-scores) The average provider directory is roughly 50% inaccurate (CMS). Rather than simply displaying potentially inaccurate data, Ribbon uses confidence scores to indicate the likelihood that any given provider’s contact information (i.e., address and phone number) is accurate. Since manual validation across every data point on a continual basis is not effective at scale, confidence scores show the relative accuracy of each data point without manual confirmation. A confidence score of one (1) indicates a low likelihood the data is accurate (i.e., a high likelihood of inaccuracy), while a confidence score of four (4) indicates a high likelihood the data is accurate. A confidence score of five (5) indicates confirmed accuracy via manual validation by Ribbon’s call center. This manual validation is then leveraged by Ribbon’s ML model which learns from this validated data to predict the relative accuracy of a provider’s contact information. ### How does the model work? [](#how-does-the-model-work) Ribbon collects data from thousands of sources to identify all instances of a given provider’s National Provider Identifier (NPI), address, and phone number. Ribbon’s ML model then cleanses, standardizes, and “scores” that data to determine the likelihood that any given provider’s contact information is accurate. Ribbon trains the ML model that powers confidence scores on a subset of manually validated contact information regularly to ensure continued accuracy. The ML model runs the aggregated data against this validated subset to predict the relative accuracy of all data points at scale. Additionally, Ribbon will also manually validate a random sample of the ML model’s output to assess if confidence scores match predicted probability benchmarks. For example, a random sample test should show that 90% of providers with a confidence score of four (4) are accurate after manual validation. > 📘 > > How does confidence score map to accuracy? > > > ------------------------------------------------ > > **5** indicates that the data point has been manually verified within the past 90 days. > **4** represents a 90% probability of being accurate > **3** represents a 70% probability of being accurate > **2** represents a 50% probability of being accurate (industry average) > **1** represents a 20% probability of being accurate Updated 9 months ago * * * --- # Specialties ### What is it? [](#what-is-it) Ribbon’s specialties identify the clinical specializations of a given provider. ### Why is it useful? [](#why-is-it-useful) Specialties are one of the most used and displayed fields in Ribbon’s directory because of how central it is to most “find care” stories. Most searches for a clinician start with a basic parameter of what type of clinician is needed, and the specialty (be it “Orthopedics” or “Cardiology” or “Physical Therapy”) is how we categorize and label clinicians. Mirroring the reality of clinical practice, a single clinician can have several specialties in our data. For some clinicians, Ribbon defines a “primary specialty” among the set assigned. Our customers typically interact with this feature by creating some sort of “select” functionality (e.g. a drop-down, or a fuzzy search) that interacts with the `/specialties` reference index and then passes the selected options to a search in the `/providers` endpoint. ### Methodology [](#methodology) Ribbon’s specialty options largely use the NUCC specialty taxonomy as a base, and our specialty attributes include the associated taxonomy code where available. In some instances, we’ve added or removed specialties from that set as we have learned about how customers think about search. Ribbon assigns specialties (and selects a clinician’s “primary specialty”) for specific clinicians through a tiered process that synthesizes several sources including NPPES, as well as public and private sources. ### FAQs: [](#faqs) * Can I search for groups of specialties? \-> Yes! Our [Specialty Guide](/docs/search-for-specialties) has more information on how to search for commonly associated specialties (i.e: all Dermatology specialties) Updated over 1 year ago * * * * [Specialties Guide](https://ribbon.readme.io/v2.2/docs/search-for-specialties) * [Specialties Documentation](https://ribbon.readme.io/v2.2/reference/getspecialties) --- # Networks ### What is it? [](#what-is-it) Ribbon's insurance data set provides information about the different insurance plans in the US healthcare system, and guidance on which providers accept those plans. You can use Ribbon’s insurance data to find providers that are in-network or out-of-network for a given insurance plan and see a full list of insurance plans accepted by a given provider. ### Why is it useful? [](#why-is-it-useful) Without insurance information, patients may have to call multiple practices to find one that accepts their plans. With Ribbon’s insurance data, patients can quickly navigate to the subset of providers that are in network with their plan, saving money and helping them get the care they need. ### Methodology [](#methodology) Ribbon captures insurance network data directly from payer directories, claims, machine-readable files, and other publicly available sources. Given insurance data is often messy and incomplete, we employ a number of automated and manual processes to categorize health plans efficiently. From there, we normalize, geocode, and map each entry in our insurance data sets to the corresponding provider location in our core directory product. ### FAQ [](#faq) * Why do Insurance objects have a confidence score of 4? \-> Ribbon's Insurance data is extracted directly from payer websites. Because Ribbon Insurance data is at par with payer websites, we have a relatively high confidence that the data is accurate. Updated 9 months ago * * * * [In-Network Search Guide](https://ribbon.readme.io/v2.2/docs/search-networks) * [Insurances Endpoint Documentation](https://ribbon.readme.io/v2.2/reference/getinsurances) --- # Ribbon Products Overview [](#overview) -------------------------- Ribbon has consolidated its product offering into the following packages: _Foundation, Startup, and Data Toolkit_. These correspond to different data attributes and customizations available in Ribbon's API (shown in the table below). _Add-Ons_ aren't available within any specific package. Rather, they are available for purchase alongside available Ribbon packages. > 📘 > > Don't know which of these packages you fall under? > > > -------------------------------------------------------- > > Reach out to your Customer Success Manager or [\[email protected\]](/cdn-cgi/l/email-protection#790a0c0909160b0d390b101b1b1617111c18150d11571a1614) > and we'll help you get everything sorted out! Product Packages [](#product-packages) ------------------------------------------ | | Foundation (& Startup) | Data Toolkit | | --- | --- | --- | | [Providers Directory](/reference/getcustomproviders) | ✅ | ✅ | | [Locations Directory](/reference/getcustomlocations) | ✅ | ✅ | | [Network (Insurances)](/reference/getinsurances) | ✅ | ✅ | | [Provider Specialties](/reference/getspecialties)
& [Location Types](/reference/getspecialties) | ✅ | ✅ | | [Focus Areas](/reference/getclinicalareas) | ✅ | ✅ | | Organizations/TINs | ✅ | ✅ | | [Custom / Boost Filters](/docs/create-a-boost-filter) | _Reach out to Ribbon for more information_ | ✅ | | [Provider Cost / Quality](/docs/aggregate-costquality-scores) | _Add-On_ | _Add-On_ | | [Eligibility Check](/reference/geteligibility) | _Add-On_ | _Add-On_ | | [Price Transparency](/reference/getpricingproviders) | _Add-On_ | _Add-On_ | | Flag Preferred Providers/Locations | ❌ | ✅ | | Additional Data Sources | ❌ | ✅ | | [Custom Fields / Data Editing](/reference/putcustomprovider) | _Reach out to Ribbon for more information_ | ✅ | | Network / Roster Ingestion | ❌ | ✅ | Updated 9 months ago * * * --- # Location Search ### Section Overview [](#section-overview) Here, we will walk through a few common workflows you can implement with the Ribbon [Locations Endpoint](/reference/getcustomlocations) . We will provide examples of API requests and the default parameters you should set. We will also tie in other Ribbon product modules that you can use to enhance search results from the `/locations` endpoint - specifically using Location Types, [Insurances](/reference/getcustominsurance) , and [Organizations](/docs/organizations-1) . If there are other use cases you would like to see here, please shoot us a message at [\[email protected\]](/cdn-cgi/l/email-protection#364543464659444276445f545459585e53575a425e1855595b) ! > 📘 > > Note > > > ---------- > > These won't cover the full list of available parameters in the `/locations` endpoint. Rather, we are choosing to display a few that we believe are immediately impactful. For a full list of available search parameters, view the [API Reference Docs](/reference/getcustomlocations) Updated over 1 year ago * * * --- # Procedure-Level Cost & Experience ### Overview [](#overview) In each of a provider's marked [procedures](/docs/procedures) , The `cost_index` and `experience_index` fields measure the provider's relative cost & experience score at performing the given procedure. The `max_cost_index` and `min_experience_index` parameters can be used to filter for providers with minimum cost and experience scores for a given procedure. To search for providers by either of these scores, we also need to include the procedure\_ids parameter (use the [Procedures Guide](/docs/search-for-procedures) to select the relevant procedure UUID). ### Search providers by Procedure Cost/Experience Scores [](#search-providers-by-procedure-costexperience-scores) To search for providers that perform relatively high-quality/low-cost colonoscopies in Chicago, IL we can perform the following API request: HTTP `https://api.ribbonhealth.com/v1/custom/providers?procedure_ids=8460eecc-371c-4dc4-bd7f-3beaeda8ced4&min_experience_index=7&max_cost_index=7&address=Chicago, IL` Updated over 1 year ago * * * --- # Procedures ### What is it? [](#what-is-it) Ribbon's Procedures indices provide three data elements to customers, all at the procedure level - * Relative experience index - how experienced is a given provider in performing a given procedure, relative to their peers? * Relative cost index - how expensive is a given provider in performing a given procedure, relative to peers in their area? * Regional cost estimate - how much does a procedure typically cost in a given geography? Information on procedures over 1000 commonly delivered procedures, including the 500 shoppable procedures identified by CMS. ### Why is it useful? [](#why-is-it-useful) Members and patients are hungry for information about how much care costs, and where to find high-value options. Ribbon's Procedures data can be used to enable a few different workflows: * Care Navigation: Search for providers by the services they offer. This provides a more granular search experience than using specialties - for example, you can specifically search for providers that perform colonoscopies rather than searching for the broader 'Gastroenterology' specialty. * Procedure Cost/Experience: See how expensive/effective a provider is at performing a specific procedure relative to their peers (on a scale of 1-10). * Procedure Cost Estimate: Find the average cost of performing a procedure within a given region. ### Methodology [](#methodology) Ribbon groups semantically similar CPT codes into single procedures based on input from clinical advisors and a quantitative analysis of billing patterns. Around 3,450 CPT Codes are represented in the index across procedures. For relative indexes, we use a statistical approach to determine relative behavior compared to a mean and map provider-level scores to a scale from 1 to 10. Updated over 1 year ago * * * * [Procedure Reference Documentation](https://ribbon.readme.io/reference/getprocedurecostestimate) * [Procedure Cost Estimate Documentation](https://ribbon.readme.io/reference/getprocedure) * [Procedure Search Guide](https://ribbon.readme.io/v2.2/docs/search-for-procedures) * [Procedure Cost/Experience Guide](https://ribbon.readme.io/v2.2/docs/procedure-level-cost-experience) --- # Introduction What Are Workflow Guides? [](#what-are-workflow-guides) ----------------------------------------------------------- Welcome to Ribbon's Workflow Guides! Whether you're new to Ribbon or not (_or maybe you're just really into reading API Docs_), we are excited to show you what Ribbon's API can do. Here, we show you how our endpoints can be configured to power care navigation use cases that fit your team’s needs exactly. Please note this section is very different from the [API Reference](/reference/getcustomproviders) section, which should be used to structure individual endpoint calls with the correct parameters. We have put together common use cases for Ribbon's API, including: * Searching for providers by geography, insurance, clinical parameters, and quality measures * Searching for Ribbon locations by geography, insurance, and offered services * Creating custom filters/boost filters to surface the most relevant providers and the difference between the two How Should You Use These Guides? [](#how-should-you-use-these-guides) ------------------------------------------------------------------------- We recommend reviewing these guides to better understand the types of workflows that Ribbon enables. If you already have an API token, you should follow along by performing the same API requests in Postman or another comparable tool. If you don't yet have your API key, please sign up at [https://www.ribbonhealth.com/try-now/](https://www.ribbonhealth.com/try-now/) Users who spend time upfront testing different workflows find the best fit with their intended use case and business goals. Still unsure of how to implement in a way that helps you reach your goals? Please reach out to [\[email protected\]](/cdn-cgi/l/email-protection#6b181e1b1b04191f2b190209090405030e0a071f0345080406) and we'll help you figure that out! Table of Contents [](#table-of-contents) -------------------------------------------- * [Provider Search](/docs/provider-search) * [Location Search](/docs/location-search) * [Cost & Quality Search](/docs/search-for-high-quality-providers) * [Network Data](/docs/network-data) * [Custom Filtering/Ranking](/docs/filteringranking) Updated over 1 year ago * * * --- # Eligibility > 🚧 > > This product is no longer being offered to new Ribbon customers > > > --------------------------------------------------------------------- > > However, we will continue to maintain eligibility for existing Ribbon customers. Please [reach out](https://go.ribbonhealth.com/try-now) > if you have any questions. ### What is it? [](#what-is-it) You can verify a patient’s coverage in real-time and access a wealth of other detailed information, such as copay and coinsurance details across different services, to allow for a more granular understanding of a member's insurance coverage. ### Why is it useful? [](#why-is-it-useful) Verifying a member's insurance coverage and benefits is a critical step in helping a member get care. The process of checking a patient’s insurance is often quite arduous, requiring photocopying a patient’s insurance card and calling the insurance carrier directly to verify benefits. Ribbon Health Eligibility Check makes this process a breeze. ### How does it work? [](#how-does-it-work) 1. You submit a request through the `/eligibility` endpoint with relevant parameters (patient name, patient DOB, member ID, and insurance carrier) 2. Ribbon makes a request to the payer for information on that patient's insurance coverage. 3. Ribbon returns coverage summary in a standard JSON format including plan information, progress on deductible and out-of-pocket, specialist copay, and coinsurance. ### FAQs [](#faqs) * _How can I check whether Ribbon's Eligibility endpoint supports a specific carrier? _\-> You can use the [insurance\_partners](/reference/geteligibilityinsurancepartners) endpoint to check available carriers. If you don't see the carrier you're looking for, please reach out to us at [\[email protected\]](/cdn-cgi/l/email-protection#bccfc9ccccd3cec8fcced5deded3d2d4d9ddd0c8d492dfd3d1) ! Updated 11 months ago * * * * [Eligiblity Documentation](https://ribbon.readme.io/reference/geteligibility) --- # Search for Procedures ### Overview [](#overview) Let’s first try searching for relevant [procedures](/docs/procedures) through the Procedures [reference endpoint](/reference/getprocedures) . We can fuzzy search for the procedure using the `search` parameter. HTTP `https://api.ribbonhealth.com/v1/procedures?search=colonoscopy` This returns a list of relevant procedures, including the UUID for `diagnostic colonoscopy`. We can also search for this procedure by its CPT code (45378) using the `procedure_code` parameter. HTTP `https://api.ribbonhealth.com/v1/procedures?procedure_code=45378` ### Search for Providers by Procedure [](#search-for-providers-by-procedure) Once we've identified the correct Ribbon Procedure UUID from the reference endpoint, we can use the `procedure_ids` to [search for providers](/reference/getcustomproviders) that perform the specific procedure. To search for providers in Denver that perform colonoscopies, let's perform the following API Request: HTTP `https://api.ribbonhealth.com/v1/custom/providers?procedure_ids=8460eecc-371c-4dc4-bd7f-3beaeda8ced4&distance=25&address=Denver` Updated over 1 year ago * * * --- # Search for In-Network Providers > 📘 > > Before using Ribbon's Network Data > > > ---------------------------------------- > > See the [Network Data Guide](/docs/network-data) > to understand how to identify the correct insurance UUID to attach in a search request. ### Search for Providers by Insurance UUID [](#search-for-providers-by-insurance-uuid) To surface in-network providers, we can use the `location_insurance_ids` parameter to filter by the insurance UUID. For example, to search for providers in `Cigna Open Access Plus`, we can perform the following API request: HTTP `https://api.ribbonhealth.com/v1/custom/providers?location_insurance_ids=ae0b1dd0-7356-41ee-8df4-871a52451eb7&address=Chicago, IL` The structure is very similar to surface in-network facilities/locations - but instead we use the `insurance_ids` parameter. To perform a similar search in the Locations Directory, we can perform the following API request: HTTP `https://api.ribbonhealth.com/v1/custom/locations?address=Chicago, IL&insurance_ids=ae0b1dd0-7356-41ee-8df4-871a52451eb7` Updated over 1 year ago * * * * [Insurances Reference Endpoint](https://ribbon.readme.io/reference/getcustominsurance) --- # Provider Search Basics ### Overview [](#overview) To perform one of our most common search workflows, we need to utilize a few parameters in the API request. To better understand how each of these parameters are implemented, please visit the linked pages in the guide. * `specialty` or `specialty_ids`: See the [Specialties Guide](/docs/specialties) for more information on Ribbon's specialties * `location_insurance_ids`: See the [Networks Guide](/docs/network-data) to understand how to use Ribbon insurance networks * `min_location confidence`: We recommend setting this value to 3 (see more information on [confidence scoring](/docs/confidence-scores) ) There are a few other fields we include in the API call to the providers’ endpoint to help narrow the scope of the search: * `Address`: String input of an address or zip code that will be interpreted and geocoded in real-time * `Distance`: Radius of providers surfaced by the API from the input address (in miles). This parameter defaults to a 10 mile radius. ### Search for in-network providers by specialty and address [](#search-for-in-network-providers-by-specialty-and-address) We can combine these parameters to surface a list of Dermatologists that accept my insurance plan in New York, City. By default, these results are sorted by distance to the input address. To change the sorting order of the API response, try adding a [boost filter](/docs/create-a-boost-filter) ! HTTP `https://api.ribbonhealth.com/v1/custom/providers?address=10013&specialty_ids=b9dc44e1-6add-41f8-8df4-a8ef9cea706a&location_insurance_ids=0082f872-5383-44de-9319-511f090fc56b&min_location_confidence=3` Updated over 1 year ago * * * --- # Location Types ### What is it? [](#what-is-it) Ribbon Location Types help identify the category of facility that best describes a service location, which can be helpful in determining what type of care can be received there. There are 30 distinct location types across imaging centers, clinics, urgent care, ambulatory centers, hospitals, and more. In the [Locations Directory](/docs/ribbon-directory) , a location is marked as having zero, one, or multiple location types, depending on the signal Ribbon has received from different sources. ### Why is this useful? [](#why-is-this-useful) Location Types are instrumental in directing patients to the right care. This is especially important in care situations where patients or users expect a facility or institution to appear in search instead of an individual clinician. For example, it may be more useful to search for 'imaging centers' rather than 'radiologists' depending on the required tests. Or a patient may need care at a nearby hospital and it doesn't matter which provider they're seeing. Similar to Specialties, our customers typically interact with this feature by creating some sort of "select" functionality (e.g. a drop-down, or a fuzzy search) that interacts with the /location\_types reference index and then passes the selected options to a search in the /locations endpoint. ### Methodology [](#methodology) Ribbon aggregates location type data from a variety of sources, including payer directories, medical claims, and publicly available data. Due to the inherent data complexity, Ribbon employs techniques including medical claims analysis, source alignment, and text analysis to accurately determine a location type. Ribbon aims to assign as granular of a location type as possible, but also doesn't label a location unless there is sufficient signal to confidently recommend it as that location type. This is to avoid harmful false positives (for example, a patient going to a location that is mislabeled as an urgent care center). Updated over 1 year ago * * * --- # Search by Organization (Locations) ### Overview [](#overview) We can use the `/organizations` endpoint to search through Ribbon's available [Organizations](/docs/organizations-1) . For a full list of available organizations, try out the following API request: HTTP `https://api.ribbonhealth.com/v1/custom/organizations` This returns a list of the 400+ health systems and their associated providers & locations. We may want to narrow the results down to a relevant set of organizations by geography or find a specific health system. We can use the following API Request to search for available health systems within 25 miles of Manhattan: HTTP `https://api.ribbonhealth.com/v1/custom/organizations?address=Manhattan, NY&distance=25` But if we know we want to search for providers within the Honor Health System, we can much more easily find the correct organization by searching with the `name` parameter: HTTP `https://api.ribbonhealth.com/v1/custom/organizations?name=Honor Health` ### Search for Ribbon Locations within an Organization [](#search-for-ribbon-locations-within-an-organization) Equipped with the relevant Organization UUID, we can now search for locations within this health system using the `organization_ids` parameter. > 🚧 > -- > > Make sure you also include the `address` parameter in the API request. The API request defaults to New York City, so you may get 0 results if the Organization is located elsewhere. We can search for locations in the Honor Health System with the following API request: HTTP `https://api.ribbonhealth.com/v1/custom/locations?organization_ids=d6f550b4-941c-4c4d-9654-6bee589736e1&address=Phoenix&distance=50` Updated over 1 year ago * * * --- # NPI (National Provider Identifier) ### What is an NPI? [](#what-is-an-npi) The National Provider Identifier (NPI) is a unique, 10-digit identification number assigned to healthcare providers and entities in the United States. The NPI is a standard established by the Centers for Medicare & Medicaid Services (CMS) under the Health Insurance Portability and Accountability Act (HIPAA) of 1996. Its primary purpose is to simplify healthcare administrative processes and improve efficiency by providing a standardized way to identify healthcare providers. NPIs apply to both providers and healthcare entities. There are a few important differences to note between the two: * **Type 1 NPIs** are unique and permanent. Every provider (including nurses and counselors) has an NPI and their NPI is never reassigned, even if they stop practicing or are deceased. There is a 1:1 relationship between provider and NPI - in other words, every provider gets one NPI. * **Type 2 NPIs** apply to healthcare entities, such as clinics, hospitals, and pharmacies. Many locations in Ribbon's `/locations`directory have a corresponding NPI. However, there is a lack of standardization in how these NPIs should be used. NPIs can apply to individual clinics (try searching for NPI 1487840252 in [NPPES](https://npiregistry.cms.hhs.gov/searchNPPES) ) or entire organizations. ### FAQs [](#faqs) * _Can I search for providers by NPI?_ \-> Yes! Check out the [Find a Provider](/docs/find-a-specific-provider) Guide Updated over 1 year ago * * * --- # Location Search Basics ### Overview [](#overview) For most use cases, we recommend setting the following parameters by default in `/locations` [endpoint](/reference/getcustomlocations) requests: * `min_confidence`: We recommend setting this value to 3 to ensure high-quality results (see more information on [confidence scoring](/docs/confidence-scores) ) * `address`: String input of an address or zip code that will be interpreted and geocoded in real-time. Here's an example request using those parameters: HTTP `https://api.ribbonhealth.com/v1/custom/locations?address=New York City, NY&min_confidence=3` This request returns thousands of locations, making it difficult to identify a relevant facility to direct patients. You can further narrow down to relevant locations by filtering on insurance plans and location types! ### Search for in-network locations by address and location type [](#search-for-in-network-locations-by-address-and-location-type) * `location_type` : View the [Location Types Guide](/docs/search-for-location-types) to understand how to apply this parameter * `insurance_ids`: View the [Networks Guide](/docs/network-data) for more information on how to use Ribbon insurance networks We can combine these to surface imaging centers that accept my insurance plan in New York City with the following request: HTTP `https://api.ribbonhealth.com/v1/custom/locations?address=New York City, NY&insurance_ids=0082f872-5383-44de-9319-511f090fc56b&min_confidence=3&location_types=Imaging Center` Updated over 1 year ago * * * --- # Cost & Quality ### What is it? [](#what-is-it) Outcomes Quality - A provider's overall outcomes quality score measures how the provider's outcomes are compared to those of clinicians treating similar types of patients. The score includes factors such as readmission rates, patient mortality rates, avoidable ER visit rates, etc. Cost efficiency - A provider's overall cost efficiency score measures how expensive they are compared to providers treating similar types of patients. This measure includes elements of both "unit price" (how much they charge for a particular service) and utilization (how many services they prescribe per patient, compared to what other providers do under similar circumstances). _This is a premium feature and may not be enabled in your API index. Please reach out to Ribbon Support ([\[email protected\]](/cdn-cgi/l/email-protection#61121411110e131521130803030e0f0904000d15094f020e0c) ) for additional information on accessing Ribbon Cost/Quality!_ ### How is it measured? [](#how-is-it-measured) Ribbon provides two scores for each provider - one for cost efficiency, and one for outcomes quality. Both scores range from 1 to 5, with a score of 5 being the best (higher quality or more cost-efficient) and a score of 1 being the worst (lower quality or less cost-efficient) Unlike episode or procedure-specific scores, these metrics reflect the provider's overall performance across the different parts of their care for which we have data. ### Methodology [](#methodology) Ribbon's provider cost and quality data comes from our channel partner, CareJourney. Currently, CareJourney is methodologically focused on the highest-cost specialties where coverage is much higher (cardiology and gastroenterology, for example). These are often the areas where having a score is most impactful because these specialists control so much spend – i.e. setting care paths that contribute to medical expense beyond just what they personally deliver to include care others deliver (like imaging, physical therapy, drug spend, and the positive and negative impacts of the patients’ outcomes). In particular, CareJourney struggles with coverage in specialties where major episodes of care are not attributed (such as anesthesiology, radiology, dermatology, and physical therapy). ### FAQs [](#faqs) * _Why doesn't a provider have a cost and quality score?_ \-> A provider may practice a specialty that falls outside of CareJourney's current methodology. Alternatively, there may be a low number of available claims for the particular provider. Since there's no single unified claims dataset, any provider performance measurement is dealing with a variably incomplete view of a provider's overall practice. * _What is a 'good' cost & quality score, and what score should I filter by in Ribbon's API?_ \-> The C&Q data is evenly distributed by quintile - 20% of doctors have a CJ score of 1, 20% have a 2, and so on. While there isn’t a specific threshold on the effectiveness of a provider at each level, it does indicate how they’re performing relative to their peers. The minimum threshold you set for these values depends on the tradeoff you’re looking to make between coverage and quality. We generally recommend setting a minimum threshold of 3 to filter out ‘lower’ quality providers but maintain a high enough coverage. Updated 10 months ago * * * * [Cost & Quality Guide](https://ribbon.readme.io/v2.2/docs/aggregate-costquality-scores) --- # Search for Location Types ### Overview [](#overview) You can use the Location Types [reference endpoint](/reference/getcustomlocationtypes) to search through Ribbon's available [location types](/docs/location-types) . Note, this endpoint doesn't include `/custom` in the request URL like most of our other endpoints. To see all location types, you can perform the following request: HTTP `https://api.ribbonhealth.com/v1/location_types` Your team can use this endpoint to power a dropdown for users to select the relevant location type or to identify the relevant ones ahead of time. The display\_name can be used as an input to the `/locations` endpoint through the `location_types` parameter. **The parameter accepts an exact match of the display\_name string found in the reference endpoint**. JSON `{ "uuid": "b5458763-968e-4690-bc70-f29d3a7459a9", "display_name": "Ambulatory Surgery Center" }, { "uuid": "ce353de6-a20b-4283-9162-93b3b9be9570", "display_name": "Assisted Living Facility" }, { "uuid": "23d2210d-64b8-4c63-9429-61a3cadb8ad5", "display_name": "Clinic" }, { "uuid": "14d639bf-c0f8-4d59-b437-da3c5931a270", "display_name": "Clinic - Dental" }` _partial response from location\_types endpoint_ ### Search for locations by location type [](#search-for-locations-by-location-type) Try out the following request to surface imaging centers in New York City! HTTP `https://api.ribbonhealth.com/v1/custom/locations?address=New York City, NY&min_confidence=3&location_types=Imaging Center` Updated over 1 year ago * * * --- # Find a Specific Provider ### Search by NPI [](#search-by-npi) The best way to surface a specific provider is by direct lookup, using their unique [NPI](/docs/npi-national-provider-identifier) . HTTP `https://api.ribbonhealth.com/v1/custom/providers/1114956380` In the response, we can see all relevant information for this provider, including their name, education, specialties, locations, contact information, and accepted insurance plans. > ❗️ > -- > > You cannot use the `fields` or `_excl_fields` parameter when performing an NPI lookup. ### Search by Name [](#search-by-name) We may not have the provider’s NPI available and are instead relying on name and address identifying information. We can use the `name` parameter in the `/providers` endpoint, which accepts a string input of the provider’s first, last, full name, or partial input (i.e.: first initial + last name). We can narrow down the list of search results by filtering on address. Let’s assume our provider practices in Chicago and search by the zip code 60611. The below request returns ~10-20 providers, which we can use to match to the correct provider. HTTP `https://api.ribbonhealth.com/v1/custom/providers?name=james hall&address=60611` > 📘 > > **Note** > > > -------------- > > The ‘name’ parameter fuzzy search is optimized for ‘first\_name last\_name’ inputs. > > If your use case requires searching by a provider’s initials (ie: J. Hall) or including a middle name, please reach out to Ribbon at [\[email protected\]](/cdn-cgi/l/email-protection#74070104041b060034061d16161b1a1c111518001c5a171b19) > and we can help you configure an optimized provider search. Updated over 1 year ago * * * --- # TINs ### What are TINs? [](#what-are-tins) TINs are 9-digit unique tax identification numbers used to represent unique billing entities. TINs are used by healthcare organizations to identify themselves as the associated billing entity on administrative documents including billing statements, claim forms, and tax returns. It is important to note that billing entities do not align 1:1 with the healthcare organizations we are familiar with in the market as distinct organizations. ### Ribbon's TINs dataset [](#ribbons-tins-dataset) Our TINs data maps the relationship between TINs and NPIs, Locations and associated TINs/Billing entities. We can map the following different relationships: * TIN <> Location <> NPI * TIN <> Location * TIN <> NPI ### The data [](#the-data) * `tin`: 9 digit identification code used by the IRS for business entities and used for contracting and paying provider/facility claims * `name`: The billing entity name that appears on claims data, or if available, the official legal name of the billing entity. * `legal_name`: The legal name of the entity associated with the TIN * `address`: The address of the organization associated with the TIN. This could be the primary service location or billing location * `tin_confirmed`: A yes/no field that assesses whether a TIN is likely to be confirmed or requires additional nreview. The field is powered by business logic that triangulates IRS data and claims data. ### Methodology [](#methodology) TINs data is compiled from a breadth of accredited data sources, including the IRS, IQVIA, PECOS, AHA, Claims, secondary payer & health system sources. Ribbon applies business logic to create TIN name field and TIN confirmed field: * Tin confirmed is informed by IRS data and/or if a TIN has a claim recently (between 6 months and one year). * TIN entity names are created by evaluating the following information: * IRS name * Claims name * Most common name Updated 6 months ago * * * --- # Focus Areas ### What is it? [](#what-is-it) Ribbon Provider Focus Areas enable you to personalize provider recommendations by surfacing rich information on the conditions a provider treats, treatments a provider performs, and provider-patient panel demographics. “Clinical Areas” describes the general area of expertise for a given provider (e.g., Knee, Wrist). “Conditions” describes the areas a patient would need care (e.g., “knee pain”). “Treatments” are the types of procedures that a provider performs to treat a given condition (e.g., “knee x-ray,” “knee scope”). “Patient panel” demographics describe the types of patients a provider usually sees based on age and gender. Ribbon users can use focus areas to power a more accurate search experience, replacing (or augmenting) searches by specialty or procedure. ### Why is it useful? [](#why-is-it-useful) Medical specialties are often not specific enough to find the particular type of care that a patient needs, requiring calls to multiple practices to find one that fits. Ribbon’s focus areas allow you to quickly and confidently drill down to the subset of providers that are a good fit for the patient. ### Methodology [](#methodology) Ribbon compiles focus areas from a database with billions of claims to identify the most common diagnoses and procedures a provider delivers alongside aggregate demographic information of the patients they treat. Ribbon’s algorithms sift through a large volume of claims data to cluster similar CPT and ICD-10 codes together to create a more useful taxonomy of procedures and diagnoses for search purposes. We then apply a topic modeling approach to identify the subset of procedures and diagnoses that accurately represent a provider’s focus. ### FAQs [](#faqs) * _Why doesn’t a specific provider have any Focus Areas? _\-> We largely rely on claims to populate our Focus Areas dataset. A provider may not have enough claims available to assign a given focus area with statistical significance. In these instances, we believe it's more impactful to not assign any focus area to the given provider. Alternatively, the provider may focus on more uncommon specialties that aren't currently captured by Ribbon's Focus Areas. Updated over 1 year ago * * * * [Focus Areas Documentation](https://ribbon.readme.io/v2.2/reference/getclinicalareas) --- # Cost & Quality Search There are a few different ways to restrict provider search by cost/quality measures. **Aggregate Cost/Quality** Ribbon's [Cost/Quality data](/docs/cost-quality) provides an aggregate score for a provider relative to their peers across all procedures. We recommend using this score to filter for high-quality providers when the specific procedure isn't known. _Note, this is a premium feature and may not be enabled in your API index. Please reach out to Ribbon Support ([\[email protected\]](/cdn-cgi/l/email-protection#c4b7b1b4b4abb6b084b6ada6a6abaaaca1a5a8b0aceaa7aba9) ) for additional information on accessing Ribbon Cost/Quality!_ **Procedure Level Cost/Experience Score** This provides a cost and experience score at the provider-procedure level. We recommend using this score when the desired [procedure](/docs/procedures) is known. **Patient Satisfaction Ratings** When the above cost/quality measures are missing for a provider (or the data isn't available in contract), we recommend falling back to display the patient satisfaction rating score. > 🚧 > > Are these product modules are included in your contract? > > > -------------------------------------------------------------- > > If not, you can reach out to your dedicated partnerships representative to learn more about getting access to this data. Updated 10 months ago * * * --- # Organizations ### What is it? [](#what-is-it) Healthcare organizations are defined as a collection of providers, locations, and/or resources that deliver healthcare services to meet the needs of target populations. There are many healthcare organizations that exist in the healthcare ecosystem, such as Health Systems, IPAs, Medical Groups, and ACOs. Organizations are most often used when searching for care on behalf of a patient. In particular, organizations can be helpful when you know which health system you want to refer to, but not necessarily which specific provider. We often see our partners use organization data to: * Find providers or facilities associated with a given organization * Discover organization phone numbers, addresses, IDs, or website addresses * Look up organization by name and geographic area ### Why is it useful? [](#why-is-it-useful) Organizations can help navigate patients to care in cases when they would prefer to seek care from a particular institution, regardless of the provider or location. ### Methodology [](#methodology) Ribbon manually curates and validates a list of healthcare organizations and leverages a machine learning matching algorithm to link service locations with their corresponding organizations. Updated 10 months ago * * * * [Organizations Guide](https://ribbon.readme.io/v2.2/docs/search-for-providers-by-organization) * [Organizations Documentation](https://ribbon.readme.io/v2.2/reference/getorganizations) --- # Search by Organization (Providers) ### Overview [](#overview) Similar to searching for [Locations by Organization](/docs/search-for-organizations-1) , we can search for Ribbon Organizations using the /organizations [endpoint](/reference/getorganizations) . If we want to search for providers within the Honor Health System, we can find the relevant Ribbon Organization UUID by searching with the `name` parameter: HTTP `https://api.ribbonhealth.com/v1/custom/organizations?name=Honor Health` Alternatively, if we want to search for any health system around New York City, we can use the `address` parameter to search more broadly: HTTP `https://api.ribbonhealth.com/v1/custom/organizations?address=Manhattan, NY` ### Search for Providers within an Organization [](#search-for-providers-within-an-organization) With the relevant Organization UUID, we can search for providers in the Health System using the `location_organization_ids` parameter. > 🚧 > -- > > Make sure you also include the `address` parameter in the API request. The API request defaults to New York City, so you may get 0 results if the Organization is located elsewhere. We can search for providers Honor Health System with the following API Request: HTTP `https://api.ribbonhealth.com/v1/custom/providers?location_organization_ids=d6f550b4-941c-4c4d-9654-6bee589736e1&address=Phoenix&distance=50` Updated over 1 year ago * * * --- # Patient Satisfaction Rating ### Overview [](#overview) The patient satisfaction rating for a given provider can be found in the `ratings_avg` field of the API response. Given the source of this data is more subjective and less rigorously evaluated than other cost/quality measures, we don't heavily recommend using this as a filter parameter. Rather, it can be displayed to your users as an **additional** data point when they're making care decisions. ### Search by Patient Satisfaction Rating [](#search-by-patient-satisfaction-rating) However, if you would still like to filter by this rating, you can use the `min_rating` parameter to filter by a minimum `patient_avg` value! Here, we can search for providers in Chicago with a minimum patient satisfaction rating of 6/10. HTTP `https://api.ribbonhealth.com/v1/custom/providers?address=Chicago, IL&min_rating=6` Updated over 1 year ago * * * --- # Search for Specialties ### Overview [](#overview) Each of Ribbon's [Specialties](/reference/getcustomspecialty) has a unique UUID and set of attributes that correspond to information found in the NUCC taxonomy. You can use the `specialty` or `specialty_ids` parameters to search for providers by these specialties in Ribbon's `/providers` [endpoint](/reference/getcustomproviders) . There are important differences between the two: * `specialty_ids` searches for provider by the **exact** Ribbon specialty UUID, which corresponds to a distinct specialty in the NUCC Taxonomy). * `specialty` searches for providers by specialty groupings. Don't worry, we'll explain more! **Specialty Groupings** Searching for individual specialties can be too granular and lead to low coverage. These granular specialties may not even be needed to navigate patients to the right parameter. We may want to see a cardiologist - it doesn't particularly matter what kind. Ribbon has created groupings of specialties to allow users to search for these broader specialty categories. For example, the 'Gastroenterology' grouping maps to individual specialties for Gastroenterology, Hepatology, Pediatric Gastroenterology, and a few others. These groupings are exposed through the `specialty` parameter. In each API request, you can see a full list of the grouped specialties in the `inclusions` field of the response. HTTP `https://api.ribbonhealth.com/v1/custom/providers?specialty=Gastroenterology` JSON `"inclusions": { "specialty_ids": [ "cf328877-90b9-4b15-9ab4-10f325ffb909", "b9dc44e1-6add-41f8-8df4-a8ef9cea706a", "28aaf52d-982d-43ed-836f-81223445f545", "35658ab3-8ed3-4ad4-939a-c8f05e4fcb80", "3ed5ced6-217e-4037-8784-fe5afad0879b" ] }` **Specialty UUIDs** We may actually just want to search by individual specialties using the `specialty_ids` parameter. Let's search for a specific Gastroenterology UUID in the `/specialties` reference endpoint. This returns a short list of closely matching specialties, which we can narrow down to the most relevant one for our provider search. HTTP `https://api.ribbonhealth.com/v1/custom/specialties?search=Gastroenterology` ### Search for Providers by Specialty [](#search-for-providers-by-specialty) Let's try searching for gastroenterologists in Denver. As mentioned before, we can use either the `specialty` parameter: HTTP `https://api.ribbonhealth.com/v1/custom/providers?specialty=Gastroenterology&address=Denver` or alternatively, the `specialty_ids` parameter: HTTP `https://api.ribbonhealth.com/v1/custom/providers?specialty_ids=ca571ba5-da97-4c9a-8289-2aaac198d4b2&address=Denver` In the API response, we can see that using the `specialty` parameter returns a higher count of providers. This is expected - the Ribbon API is matching on the larger set of specialty UUIDs. > 📘 > > Which parameter should I use? > > > ----------------------------------- > > That depends on the level of granularity you're looking for in search requests. Using the `specialty` parameter can expand coverage, but it will also return a broader range of related specialties than the more specific `specialty_ids` specialty search. ### Primary Care Specialty [](#primary-care-specialty) Primary care is not a specialty recognized by the National Plan and Provider Enumeration System (NPPES). This makes it challenging to identify providers as PCPs. Ribbon has created a PCP specialty that applies custom logic to determine whether a provider is likely to be a PCP based on available specialty information. However, this specialty (UUID `0c949aa8-6729-41c2-9d3a-5bd4a6966363`) isn't directly assigned to any providers and thus cannot be searched using the `specialty_ids` parameter. **Inclusion/Exclusion Logic** As mentioned above, Ribbon has created custom logic to identify a provider as a PCP based on their assigned specialties in NPPES. If a provider is associated with 1 or more specialties on the inclusion list below, without any specialties _not_ on the list, they would be considered eligible to be a PCP. For instance: * Internal Medicine & Internal Medicine Critical Care Medicine = Not PCP * Family Medicine = PCP * Family Medicine & Adult Medicine = PCP Inclusion List: * Internal Medicine, 475b20fc-c188-4ca1-8e3a-b0614b8f8ce2 * Internal Medicine - Geriatric Medicine, 70da755b-f382-4957-a0d0-cb41b2d45d70 * Internal Medicine - Adolescent Medicine, 31ff2eb3-559e-4b32-88e3-19654457633e * Family Medicine, 18d8ad26-7e5f-44ac-9afa-966efb375344 * Family Medicine - Geriatric Medicine, 058148f1-3a99-4bbe-9722-6c2a54ddb860 * Family Medicine - Adult Medicine, ec41ff31-571d-422e-a8b5-806bed6a6c04 * Family Medicine - Adolescent Medicine, a1539b13-b557-437b-aae4-9ff241171020 * Pediatrics, d6f8893a-9637-4565-8202-1173e02c0979 * Pediatrics - Adolescent Medicine, 210f358e-d037-49aa-9891-f1f655fc64ec * General Practice, e5047409-3007-4a04-aff9-07604bd10287 * Nurse Practitioner - Primary Care, 5d8058f9-b2c7-4556-8870-22d47b2ec03c * Nurse Practitioner - Gerontology, 74a88d8d-6dcc-45d2-ac9c-5bbff6a2fc6b * Nurse Practitioner - Family, 066e8fe9-45e1-486c-b80f-7b93708bb329 * Nurse Practitioner - Women's Health, c350d7ac-f912-4909-8a3d-7aebd46c5c70 * Nurse Practitioner - Pediatric, bf8fb610-7aa8-4ced-b9e1-98d1ec13c2e2 * Primary Care Provider, 0c949aa8-6729-41c2-9d3a-5bd4a6966363 **How to search for PCPs** We can surface primary care providers in the API by searching for providers with the `specialty` parameter ‘Primary Care’. You can combine this specialty parameter with other relevant parameters, (ie `address`, `location_insurance_ids`, `min_location_confidence`, etc.) to further narrow down search results. HTTP `https://api.ribbonhealth.com/v1/custom/providers?address=Chicago,IL&distance=5&specialty=Primary` > 🚧 > > What if I'm already using specialty\_ids? > > > ----------------------------------------------- > > That's okay! You can split your provider search experience to use the `specialties` parameter when searching for PCPs and the `specialty_ids` parameter for other specialty searches. Updated over 1 year ago * * * * [Specialties Reference API](https://ribbon.readme.io/reference/getcustomspecialty) --- # Provider Search ### Section Overview [](#section-overview) Here, we will walk through a few common workflows you can implement with the Ribbon [Providers Endpoint](/reference/getcustomproviders) . We will provide examples of API requests and the default parameters you should set. We will also tie in other Ribbon product modules that you can use to enhance search results from the endpoint - specifically using [Specialties](/docs/specialties) and Procedures. And we'll show you how to use the `/providers` endpoint to find specific providers. If there are other use cases you would like to see here, please shoot us a message at [\[email protected\]](/cdn-cgi/l/email-protection#44373134342b363004362d26262b2a2c212528302c6a272b29) ! > 📘 > > Note > > > ---------- > > These won't cover the full list of available parameters in the `/providers` endpoint. Rather, we are choosing to display a few that we believe are immediately impactful. For a full list of available search parameters, view the [API Reference Docs](/reference/getcustomproviders) Updated over 1 year ago * * * --- # Aggregate Cost/Quality Scores _This is a premium feature and may not be enabled in your API index. Please reach out to Ribbon Support ([\[email protected\]](/cdn-cgi/l/email-protection#bfcccacfcfd0cdcbffcdd6ddddd0d1d7daded3cbd791dcd0d2) ) for additional information on accessing Ribbon Cost/Quality!_ ### Overview [](#overview) [Aggregate Cost/Quality](/docs/cost-quality) scores surface in the `performance` object of the provider response. The `efficiency_index` and `outcomes_index` fields within this object store the cost and quality measures for the provider respectively. The `min_efficiency_index` and `min_outcomes_index` can be used to filter for providers with minimum cost and quality scores respectively. To search for providers in the upper half of both measures, we can set both parameters to 3 in the API request. ### Search Providers by Cost/Quality [](#search-providers-by-costquality) To search for Dermatology providers and filter by these cost/quality metrics we can perform the following request: HTTP `https://api.ribbonhealth.com/v1/custom/providers?min_efficiency_index=3&specialty=Dermatology&address=Chicago, IL&min_outcomes_index=3` JSON `"performance": { "aggregate": { "cost": { "efficiency_index": 4 }, "quality": { "outcomes_index": 4 } } }` _sample cost/quality scores in API response_ Updated 10 months ago * * * --- # User Dropdown ### Overview [](#overview) If you're creating a patient-facing navigation tool or the referring clinician has easy access to members' insurance plans, we recommend building an insurance dropdown to select the relevant insurance plan. You can break down the insurance selection process into two steps, carrier selection and plan selection. > 📘 > > You will need to cache Ribbon's Insurance Data > > > ---------------------------------------------------- > > You will need to cache Ribbon's `/insurances` [reference endpoint](/reference/getcustominsurance) > to enable this workflow (there is no endpoint available yet to surface a list of available carriers). **Remember to update this cache monthly** to avoid surfacing stale insurance data. **Carrier Selection** Users can choose from a list of available Ribbon carriers. There are ~700 available carriers, so if your target population focuses on a subset of these carriers, we recommend limiting to those in the cached dataset. You can use `carrier_name` field in the Ribbon Insurance object to populate a list of all available carriers. ![](https://files.readme.io/020d2a3-Screenshot_2023-08-10_at_10.54.43_AM.png) **Plan Selection** Once your user has selected their carrier, you can filter for all available insurance plans by a given carrier name. Large carriers (like Aetna or Cigna) will return a large set of insurance plans, given the size of these payers. To help narrow down the list of plans as your users are searching, you can build a search bar that matches string input to available plans. Please reach out to your [\[email protected\]](/cdn-cgi/l/email-protection#63101613130c111723110a01010c0d0b06020f170b4d000c0e) if you need help building this out! ![](https://files.readme.io/e506d42-Screenshot_2023-08-10_at_9.56.36_AM.png) Updated over 1 year ago * * * --- # Filtering/Ranking _These are premium features and may not be enabled in your API index. Please reach out to Ribbon Support ([\[email protected\]](/cdn-cgi/l/email-protection#8ffcfaffffe0fdfbcffde6edede0e1e7eaeee3fbe7a1ece0e2) ) for additional information on accessing custom/boost filters!_ ### Overview [](#overview) Does the [search parameter](/reference/getcustomproviders) you're looking for not exist? Maybe you want to return only Spanish-speaking providers and Ribbon doesn't expose an easy filter parameter for that use case. Or do you want to the search results to be ranked by something other than address? Perhaps you'd like to see the highest confidence providers at the top while keeping lower confidence ones at the bottom of the search results. Where Ribbon's core search parameters don't fit your use case, there are two ways you can modify the search results from Ribbon's API, custom filters and boost filters. The correct filter to use depends on whether you want to completely remove 'less relevant' search results or push them to the bottom of search results. ### Custom Filters [](#custom-filters) Ribbon's custom filters only return relevant search results while removing providers that don’t pass the filter criteria. We recommend using custom filters when the filtered results aren't at all relevant to navigating patients to care. Many of Ribbon's provider/location search parameters act as filters, so check if there's a default parameter you can use before creating a custom filter! ### Boost Filters (Ranking) [](#boost-filters-ranking) For most of our standard filters and custom filters, providers or locations that don't match our search query won't appear in the returned results. However, these non-matching providers/locations may still be relevant to the user! Boost Filters are a type of filter\_type which "boosts" **providers or locations** that match our search query to the top of our results while keeping non-matching yet potentially relevant options near the bottom of our results. This can be useful where it's important to still return results where coverage can be low in a specific geography/specialty. Updated 10 months ago * * * --- # Network Data ### Overview [](#overview) Ribbon creates unique identifiers (UUIDs) for each insurance plan that we collect. These UUIDs are used to facilitate searches for in-network providers or locations through Ribbon's API. Mapping your member’s insurance plan to these Ribbon UUIDs is a critical part of integrating Ribbon’s network data into your existing workflows. We recommend addressing this exercise as early as possible to avoid any roadblocks to launching with Ribbon's API. We often guide our customers to one of two solutions outlined below, depending on use case and the users navigating care (patients, clinicians, etc.). * **[User Dropdown](/docs/user-dropdown) **: members/patients can select their relevant insurance plan via a dropdown, and the selected UUID is applied to the provider/location search * **[Network Mapping:](/docs/network-mapping)** The member/patient's insurance plan is mapped to a Ribbon UUID _prior_ to performing the search > ❗️ > -- > > If you think that both of the below solutions won't work for your team, please reach out **as soon as possible**, so we can help you explore alternatives. Once the user has selected their relevant plan, you can pass the associated UUID into provider and location search requests. See the In-Network Provider Search and [Location Search Basics](/docs/location-search-basics) Guides on how to apply these parameters! Updated over 1 year ago * * * --- # Include/Exclude Fields from API Response ### Overview [](#overview) The `fields` parameter is an inclusive filter that accepts a comma-separated string of field names to _include_ on Provider objects. The `_excl_fields` parameter is an exclusive filter that accepts a comma-separated string of field names to _exclude_. ### Example [](#example) Before we try applying either of these parameters, let's try a basic [provider search](/reference/getcustomproviders) request: HTTP `https://api.ribbonhealth.com/v1/custom/providers?specialty=Dermatology&address=10014` In the API Response, we see there's a lot of valuable detailed data that Ribbon provides in the response. But searching for the entire Provider object can be time intensive - some providers have tens of thousands of rows of data across the `locations` and `insurances`. Instead, if we know which fields we need, we can narrow the response size to make searches blazingly fast! For this example, let's say we only care about the locations a provider practices at. Let's use the `fields` parameter to narrow down the response: HTTP `https://api.ribbonhealth.com/v1/custom/providers?specialty=Dermatology&address=10014&fields=locations` You can see this reduces the size of the response by more than half! ### Exclude Fields [](#exclude-fields) Similarly, if we care about every field **except** locations, we can exclude from the API Response with the `_excl_fields` parameter: HTTP `https://api.ribbonhealth.com/v1/custom/providers?specialty=Dermatology&address=10014&_excl_fields=locations` If you try this out, you'll see that locations are nowhere to be found in the response! Both of these methods reduce the response time of requests and allow you to build more delightful user experiences using Ribbon's API. Updated over 1 year ago * * * --- # Rate Limits See below for details regarding rate limits for each of our endpoints. A **Too Many Requests (429):** `rate_limit_exceeded` error will be returned if a given rate limit is hit. | Endpoint | Rate Limit | | --- | --- | | `v1/custom/providers` | 1,000 calls / min | | `v1/custom/providers/{npi}` | 5,000 calls / min | | `v1/insurances` | 1,000 calls / min | | `v1/specialties` | 1,000 calls / min | | `v1/custom/locations` | 1,000 calls / min | | `v1/custom/locations/{uuid}` | 5,000 calls / min | | `v1/conditions` | 1,000 calls / min | | `v1/deductible` | 1,000 calls / hr | Updated over 1 year ago * * * --- # Network Mapping ### Overview [](#overview) The [User Dropdown](/docs/user-dropdown) may not always be the preferred option for customers as it puts the onus of selecting the appropriate Ribbon network on the end user (whether this is a patient, clinician, referral coordinator, etc.). In these cases, you may choose to instead surface your members’ insurance plans within your UI and map these plans to the relevant Ribbon network UUIDs on the back end. This can be a non-trivial task, given insurance plan data is often formatted in a variety of different ways across insurance cards, plan documents, and payer websites. Ribbon's insurance data, including the carrier and plan name, matches the formatting found on payer websites. Depending on the formatting of your users' plan information, you will likely need to map these insurances to Ribbon's UUIDs through a manual mapping process. We recommend mapping all available members' plans to Ribbon UUIDs before launching your product. ### Map an insurance plan [](#map-an-insurance-plan) To map a member's insurance plan to a Ribbon UUID, we recommend following the steps below. If you're still unable to map an insurance plan, please reach out to Ribbon at [\[email protected\]](/cdn-cgi/l/email-protection#11626461617e636551637873737e7f7974707d65793f727e7c) and we can help identify the correct Ribbon Insurance plan. **Identify plan information** We recommend identifying and compiling all sources of plan information available, including plan documents and relevant networks. The more information you have available, the easier it will be to search for the correct Ribbon UUID in the `/insurances` reference endpoint. At a baseline, `Carrier` and `Plan Name` are crucial to surface a relevant Ribbon Insurance plan. **Query** You can use the `/insurances` reference endpoint to query insurance plans by available plan information. The `search` parameter to input the plan name and `carrier_name` parameter to input the relevant carrier. We also recommend using the `plan_type` and `state` parameter if you're having trouble narrowing down to a reasonable list of potential plans. **Select** If you're able to identify the correct plan, that's great! You can now use the associated UUID as an input into future provider search requests. If you're unable to find the correct plan (and Ribbon UUID) from querying the `/insurances` [reference endpoint](/reference/getinsurances) , there are a few steps you can take: * Modify the query parameters! Sometimes plan names have slight discrepancies or Ribbon can't correctly assign `state` to a plan due to carrier-level limitations. Broadening the search query and relaxing parameters can potentially help surface more relevant plans. * Reach out to Ribbon at [\[email protected\]](/cdn-cgi/l/email-protection#2b585e5b5b44595f6b594249494445434e4a475f4305484446) if you still can't find the correct UUID, and we can help you resolve some of your more difficult mappings. ### Having trouble finding the right plans? [](#having-trouble-finding-the-right-plans) If you cannot find the correct insurance plan for a smaller carrier, Ribbon may not be collecting the plan. Reach out to [\[email protected\]](/cdn-cgi/l/email-protection#5b282e2b2b34292f1b293239393435333e3a372f3375383436) if this is the case and we can try to collect these new plans! > 📘 > -- > > We recommend using the API to identify relevant Ribbon UUIDs. However, upon request, Ribbon is also able to share an updated list of all of the insurance networks available in your custom index for easy viewing of available network data. Updated over 1 year ago * * * --- # Latency ### Why is there variability across API requests? [](#why-is-there-variability-across-api-requests) API latency is affected by a few factors, mainly the following: **Type of Endpoint**: Different endpoints utilize different underlying architectures. The providers endpoint uses a search infrastructure to find relevant providers across different parameters, while the reference endpoints are a direct lookup. **Query Parameters**: Using a higher number of query parameters or computationally heavy ones. Right now, `specialties` and `insurances` filtering have the highest impact on API latency. **Fields**: The number of fields included in the API response (controlled by the `fields` parameter) ### Recommendations [](#recommendations) Depending on whether your use case allows for it, we would recommend the following optimizations to Ribbon's API in order to decrease latency. * Using `fields` or `_excl_fields` [parameters](/docs/includeexclude-fields) to filter down the API response * Lowering the `page_size` (we generally recommend the default of 25) * When editing, applying the `async=true`, which will apply edits asynchronously Updated over 1 year ago * * * ---