View Provider Data

Endpoint for accessing provider data based on important parameters


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 \
  '' \
  -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": [
    "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": [
    "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": [
    "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": ",-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:{npi}?max_insurances=50

Parameter and Fields

The primary parameter for this endpoint is the desired provider's NPI:{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:

npiThe National Provider Identifier number. This should always match the NPI given, assuming we have that NPI in our database.
first_nameFirst name of provider
middle_nameMIddle name or initial of provider
last_nameLast name of provider
specialtiesThis lists all the specialties for a given doctor
specialties.is_primaryEach specialty contains an "is_primary" flag. This True/False flag indicates whether or not a specialty is a provider's primary specialty.
provider_typesThere are high level classifications for different provider types -- e.g. "Doctor", "Optometry", "Dental Providers", "Nursing", etc.
ageThe estimated age of the provider
genderThe gender of the provider
degreesLists all degrees associated with this provider (e.g. MD, OD, PhD)
languagesList of confirmed languages spoken
locationsList of all locations this provider is known to practice at including any known phone numbers at these locations.
locations.confidenceEach location contains a confidence score. This score indicates the probability of the given provider practicing at said location with the included contact information.
insurancesList of all the insurances the doctor accepts
educationsList of the schools attended by the provider
online_profilesWe aggregate profiles across a variety of different online sources, including booking platforms.
ratings_avgAverage patient satisfaction rating out of 10 points across multiple sources.
ratings_countTotal 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!