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:




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


First name of provider


MIddle name or initial of provider


Last name of provider


This lists all the specialties for a given doctor


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


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


The estimated age of the provider


The gender of the provider


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


List of confirmed languages spoken


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


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


List of all the insurances the doctor accepts


List of the schools attended by the provider


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


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


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!