View Provider Data (core)

Endpoint for accessing provider data based on important parameters

Overview

Description: The provider endpoint provides all available information on any provider.

Endpoint: v1/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

curl -X GET \
  'https://api.ribbonhealth.com/v1/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!

JSON

{
    "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"
        }
    ],
    "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": [
    ]
}

❗️

Default limit of 50 insurances at v1/providers/{NPI}

While the default response displays only the first 50 insurances for the given provider, you can add a parameter ("max_insurances") to increase or decrease that limit. For example:

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

Parameter and Fields

The primary parameter for this endpoint is the desired provider's NPI:
https://api.ribbonhealth.com/v1/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
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