Search for Providers based on Focus Areas
Overview
Description: Filter and search for providers based on the elements of our Focus Areas product: providers' clinical areas (including the conditions they treat and the treatments they perform) as well as the demographic features of their patient panel (age and sex labels).
Endpoint: /v1/custom/providers
Status: Live
Methods: GET
Example use-case: Develop more customized searches for the care need - for example: as opposed to searching for any Psychiatrist, filter to just those that primarily treat woman, and focus on PTSD.
Diving In
Searching for providers based on Clinical Areas broadly follows the general functionality of the /providers/ endpoint as described in earlier pages of our documentation. The key difference is that if you have access to Focus Areas data within your custom /providers/ endpoint, you will be able to leverage the parameters below to filter providers accordingly.
A note on applying multiple search criteria simultaneously:
In general, adding multiple search criteria within a parameter that accepts multiple inputs (like entering multiple condition_ids in the conditions_ids parameter) produces an OR search (returning all providers that match ANY of the entered criteria)
However, multiple criteria across parameters (e.g. a condition criteria and a treatment criteria) produces an AND search, returning only providers that meet both parameters' criteria.
For example:
condition = depression
panel_sexes = Primarily female
Returns providers that treat depression AND primarily treat female patients.
Search Parameters
You can also use the following parameters for provider and location searches based on procedures performed, relative experience levels, and/or relative cost effectiveness.
| Parameter | Description |
|---|---|
clinical_area | String input that is fuzzy matched to the most relevant clinical_area.display field. Only a single clinical area will be selected.Returns all providers with this clinical area. |
clinical_area_ids | Comma-separated list of desired clinical area ids. Returns all providers with a clinical area exactly matching any of the entered IDs. (Note: Use the /clinical_areas/ reference endpoint (docs) to identify relevant IDs) |
condition | String input that is fuzzy matched to the most relevant condition.display field. Only a single condition will be selected.Returns all providers with this condition. |
condition_ids | Comma-separated list of desired condition ids. Returns all providers with a conditions.uuid field exactly matching any of the entered IDs.(Note: Use the /conditions/ reference endpoint (docs) to identify relevant IDs) |
treatment | String input that is fuzzy matched to the most relevant treatments.display field. Only a single condition will be selected.Returns all providers with this treatment. |
treatment_ids | Comma-separated list of desired condition ids. Returns all providers with a treatments.uuid field exactly matching any of the entered IDs.(Note: Use the /treatments/ reference endpoint (docs) to identify relevant IDs) |
panel_ages | Comma-separated list of desired Panel Ages strings. Options are:Pediatric (0-12)Adolescent (13-21)Adult (22-44)Adult (45-64)Senior (65 and over)Returns all providers with a panel_ages label field exactly matching any of the entered strings. |
panel_sexes | Comma-separated list of desired Panel Sexes strings. Options are:Both female and malePrimarily femalePrimarily maleReturns all providers a panel sexes label field exactly matching any of the entered strings. |
Example Request - Providers
For example, we can perform a search with parameter treatment = knee to return providers that deliver knee treatments.
curl -X GET \
'https://api.ribbonhealth.com/v1/custom/providers?treatment=knee' \
-H 'authorization: Bearer <your_token>'
Example Response - Providers
We would be returned a set of providers with knee-related treatments
{
"parameters": {
"total_count": 86,
"page": 1,
"page_size": 25,
"sort_by": "distance",
"distance": 10,
"geo": {
"latitude": 40.7351327,
"longitude": -73.9881657
},
"address": "33 Irving Pl, New York, NY 10003, USA",
"treatment": {
"uuid": "88a70b34-d0a7-47e2-89ac-4fed203eca2f",
"display": "Knee Replacement"
}
},
"data": [
{
"npi": "1234567890",
"first_name": "Emily",
"middle_name": "K",
"last_name": "Smith",
"age": 50,
"gender": "f",
"ratings_count": 100,
"ratings_avg": 9.5,
"degrees": [],
"specialties": [],
"languages": [],
"educations": [],
"insurances": [],
"provider_types": [],
"locations": [],
"online_profiles": [],
"distance": 0.1,
"panel_demographics": {
"ages": [
"Adult (22-44)",
"Adult (45-64)"
],
"sexes": "Both female and male"
},
"clinical_areas": [
{
"uuid": "9ab1f796-ff18-4e5f-87bb-2e4019d1021b",
"display": "Sports Medicine",
"conditions": [
{
"uuid": "7f19a56f-396e-4bca-b3e1-d410d6036d98",
"display": "Knee Injuries"
},
{
"uuid": "e532d0ba-45ea-44ce-8cb0-e0ac8f453206",
"display": "ACL Injury"
},
{
"uuid": "70b9dc18-c7be-4a82-b313-c05403d991f4",
"display": "Meniscus Injury"
},
{
"uuid": "b041e045-d750-4536-b364-93af131343c5",
"display": "Knee Overuse Injuries"
},
{
"uuid": "497c1359-c40a-4f9f-b3af-1043006ab89d",
"display": "Knee Cartilage Damage"
},
{
"uuid": "9f485e04-03ca-4be3-abdf-65b950cc2f0e",
"display": "Shoulder Injuries"
},
{
"uuid": "8486eeb2-fe92-470f-8b4b-608aaf77b957",
"display": "Tendonitis"
},
{
"uuid": "ce8cf9f0-9495-4dc0-ad35-ed7532a12bdb",
"display": "Knee Pain"
},
{
"uuid": "8c32f9d6-0cf4-4c6a-a2dd-574f4e1f9fa4",
"display": "Shoulder Pain"
},
{
"uuid": "8df28ae3-9e62-49e4-bcac-173cdf6c77cc",
"display": "Shoulder Stiffness/Frozen Shoulder"
}
],
"treatments": [
{
"uuid": "0df1dfd8-790a-4081-9144-654e345c5043",
"display": "Knee Scope"
},
{
"uuid": "fe4c452a-f55d-4164-b0af-9f52752efb52",
"display": "Meniscus Surgery"
},
{
"uuid": "5cb7310f-d585-486b-9765-ddcc186f1b8f",
"display": "ACL Surgery"
},
{
"uuid": "4e108e3c-38de-45ed-8b45-db2956562d42",
"display": "Shoulder Scope"
},
{
"uuid": "1e29cf84-2d15-420a-8383-019928fd1c41",
"display": "Knee X-ray"
},
{
"uuid": "5ced20e0-401d-4ff0-a6a6-932bbc0cbbc8",
"display": "Leg MRI"
},
{
"uuid": "b8abe030-26a0-4fbf-8d2f-0e315f9377b9",
"display": "Rotator Cuff Surgery"
},
{
"uuid": "e6f0d59d-933b-4d6c-9694-002b3be8e97c",
"display": "Treatment Of Sports & Overuse Injuries"
}
]
}
],
"conditions": [
{
"uuid": "e532d0ba-45ea-44ce-8cb0-e0ac8f453206",
"display": "ACL Injury"
},
{
"uuid": "497c1359-c40a-4f9f-b3af-1043006ab89d",
"display": "Knee Cartilage Damage"
},
{
"uuid": "7f19a56f-396e-4bca-b3e1-d410d6036d98",
"display": "Knee Injuries"
},
{
"uuid": "b041e045-d750-4536-b364-93af131343c5",
"display": "Knee Overuse Injuries"
},
{
"uuid": "ce8cf9f0-9495-4dc0-ad35-ed7532a12bdb",
"display": "Knee Pain"
},
{
"uuid": "70b9dc18-c7be-4a82-b313-c05403d991f4",
"display": "Meniscus Injury"
},
{
"uuid": "9f485e04-03ca-4be3-abdf-65b950cc2f0e",
"display": "Shoulder Injuries"
},
{
"uuid": "8c32f9d6-0cf4-4c6a-a2dd-574f4e1f9fa4",
"display": "Shoulder Pain"
},
{
"uuid": "8df28ae3-9e62-49e4-bcac-173cdf6c77cc",
"display": "Shoulder Stiffness/Frozen Shoulder"
},
{
"uuid": "8486eeb2-fe92-470f-8b4b-608aaf77b957",
"display": "Tendonitis"
}
],
"treatments": [
{
"uuid": "5cb7310f-d585-486b-9765-ddcc186f1b8f",
"display": "ACL Surgery"
},
{
"uuid": "0df1dfd8-790a-4081-9144-654e345c5043",
"display": "Knee Scope"
},
{
"uuid": "1e29cf84-2d15-420a-8383-019928fd1c41",
"display": "Knee X-ray"
},
{
"uuid": "5ced20e0-401d-4ff0-a6a6-932bbc0cbbc8",
"display": "Leg MRI"
},
{
"uuid": "fe4c452a-f55d-4164-b0af-9f52752efb52",
"display": "Meniscus Surgery"
},
{
"uuid": "b8abe030-26a0-4fbf-8d2f-0e315f9377b9",
"display": "Rotator Cuff Surgery"
},
{
"uuid": "4e108e3c-38de-45ed-8b45-db2956562d42",
"display": "Shoulder Scope"
},
{
"uuid": "e6f0d59d-933b-4d6c-9694-002b3be8e97c",
"display": "Treatment Of Sports & Overuse Injuries"
}
]
}...24 more providers...
]
}
Updated 26 days ago