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 male
Primarily female
Primarily male

Returns 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: Token <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...
    ]
}