View Provider Data

Endpoint for accessing provider data based on important parameters

Overview

Description: The provider endpoint provides information on any provider.

Endpoint: v1/custom/providers/{NPI}

Status: Live

Example use-case: Retrieve detailed information for any provider given their NPI, such as locations, contact information, education, patient satisfaction, etc.

Diving In

To get your bearings, first view the full set of data Ribbon has on an individual provider. Input a provider's NPI (as shown below) and the output will show a variety of key fields, including but not limited to name, age, specialties, locations, accepted insurances, online profiles, etc.

Example Request

This returns all the information we have in production on a given doctor with a simple call.

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/providers/1234567890' \
  -H 'authorization: Token your_token'

Example JSON Output

The above call would return the below response complete with validated information on that doctor.

Based on this information, we can provide users with information on Dr. Jane Doe, including her demographics, languages spoken, contact information, accepted insurances, education, satisfaction scores, and much more!

{
    "npi": "1234567890",
    "first_name": "Jane",
    "middle_name": "J",
    "last_name": "Doe",
    "age": 38,
    "gender": "f",
    "ratings_count": 20,
    "ratings_avg": 9.18,
    "degrees": [
        "MD"
    ],
    "specialties": [
        {
            "uuid": "18d8ad26-7e5f-44ac-9afa-966efb375344",
            "taxonomy_code": "207Q00000X",
            "board_specialty": "Family Medicine",
            "board_sub_specialty": "None",
            "non_md_specialty": null,
            "non_md_sub_specialty": null,
            "provider_name": "Family Medicine Doctor",
            "colloquial": null,
            "taxonomy_1": "Allopathic & Osteopathic Physicians",
            "taxonomy_2": "Family Medicine",
            "taxonomy_3": null,
            "display": "Family Medicine",
            "provider_type": "Doctor",
            "is_primary": true
        }
    ],
    "languages": [
        "english"
    ],
    "educations": [
        {
            "education": {
                "name": "Stritch School of Medicine",
                "uuid": "0b26c31a-d74a-4327-9702-57753b82a126"
            },
            "type": null,
            "year": 2007
        }
    ],
    "insurances": [
        {
            "uuid": "d8addf29-1054-4ccb-b179-dda65f7fefdd",
            "carrier_association": "Aetna",
            "carrier_brand": "Aetna",
            "carrier_name": "Aetna",
            "state": "",
            "plan_name": "Aetna HealthFund Open Choice",
            "plan_type": "PPO",
            "metal_level": "",
            "display_name": "Aetna - HealthFund Open Choice - PPO",
            "network": "",
            "confidence": 4
        },
        {... 72 additional insurances ...}
        {
            "uuid": "d4357c57-76d9-4fda-94b6-16ca8869cd45",
            "carrier_association": "UnitedHealthcare",
            "carrier_brand": "UnitedHealthcare",
            "carrier_name": "UnitedHealthcare",
            "state": "",
            "plan_name": "Passport Connect Choice Plus",
            "plan_type": "",
            "metal_level": "",
            "display_name": "Unitedhealthcare - Passport Connect Choice Plus",
            "network": "",
            "confidence": 4
        }
    ],
    "provider_types": [
        "Doctor"
    ],
    "locations": [
        {
            "uuid": "f38b9fd5-1e28-4f6e-953c-1e1493b68e21",
            "name": null,
            "address": "185 Berry St # 130, San Francisco, CA 94107, US",
            "address_details": {
                "street": "185 Berry St # 130",
                "address_line_1": "185 Berry St",
                "address_line_2": "# 130",
                "city": "San Francisco",
                "state": "CA",
                "zip": "94107"
            },
            "latitude": 37.7765973,
            "longitude": -122.3919488,
            "google_maps_link": "https://www.google.com/maps/@37.7765973,-122.3919488?q=185%20Berry%20St%20%23%20130%2C%20SF%2C%20CA%2094107%2C%20US",
            "phone_numbers": [
                {
                    "phone": "4155146410",
                    "details": "primary"
                },
                {
                    "phone": "4155146420",
                    "details": "secondary"
                },
                {
                    "phone": "4155146200",
                    "details": "secondary"
                }
            ],
            "confidence": 2
        },
        {... 3 additional locations ...}
    ],
    "online_profiles": [
    ]
}

❗️

Limit insurances returned at v1/custom/providers/{NPI}

While the default response displays all insurances for the given provider, you can add a parameter ("max_insurances") to limit the number of insurances returned. For example:

https://api.ribbonhealth.com/v1/custom/providers/{npi}?max_insurances=50

Parameter and Fields

The primary parameter for this endpoint is the desired provider's NPI:
https://api.ribbonhealth.com/v1/custom/providers/{npi}

However, as mentioned above, you can also apply the "max_insurances" parameter to toggle the maximum number of insurances displayed for a given provider.

Below are the fields included in a default response from this endpoint:

Fields

Description

npi

The National Provider Identifier number. This should always match the NPI given, assuming we have that NPI in our database.

first_name

First name of provider

middle_name

MIddle name or initial of provider

last_name

Last name of provider

specialties

This lists all the specialties for a given doctor

specialties.is_primary

Each specialty contains an "is_primary" flag. This True/False flag indicates whether or not a specialty is a provider's primary specialty.

provider_types

There are high level classifications for different provider types -- e.g. "Doctor", "Optometry", "Dental Providers", "Nursing", etc.

age

The estimated age of the provider

gender

The gender of the provider

degrees

Lists all degrees associated with this provider (e.g. MD, OD, PhD)

languages

List of confirmed languages spoken

locations

List of all locations this provider is known to practice at including any known phone numbers at these locations.

locations.confidence

Each location contains a confidence score. This score indicates the probability of the given provider practicing at said location with the included contact information.

insurances

List of all the insurances the doctor accepts

educations

List of the schools attended by the provider

online_profiles

We aggregate profiles across a variety of different online sources, including booking platforms.

ratings_avg

Average patient satisfaction rating out of 10 points across multiple sources.

ratings_count

Total number of ratings collected across different sources

Keep reading to understand more complex and interesting searches you can do at the /providers/ endpoint if you aren't aware of a given provider's NPI number!