Search for Providers Based on Organization Affiliation

Overview

Description: Filter and search for providers based on organizations with which they are affiliated.

Endpoint: /v1/custom/providers

Status: Live -- Please Contact Us to Learn More

Methods: GET

Example use-case: Narrow down a provider search to only include providers that are affiliated with a health system that patients trust.

Methodology: Ribbon's provider affiliation data relies on signal that a provider has a professional relationship with a given organization, but does not currently offer information on the exact type of professional relationship. For example, if a provider is linked to a given organization in Ribbon's data, it could mean that the provider is employed, has admitting privileges, or just generally practices at locations that are part of the given organization.

📘

Organization Types

This endpoint currently contains information on Health Systems only.

We are also planning to release additional organization types (e.g., provider groups) in the future that will be included in this endpoint.

Please feel free to reach out to a Ribbon team member to learn more about our roadmap for this product!

Diving In

Searching for providers based on organizations aligns with 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 organization data within your custom /providers/ endpoint, you will be able to leverage the parameters below to filter providers accordingly.

Search Parameters

You can also use the following parameters for provider searches based on specific organizations of interest.

Parameter

Description

location_organization_ids

Comma separated list of desired organization uuids. Filters to only providers who have the given organization uuid(s) listed in the provider.organizations field.

Using this parameter will also filter the provider.locations returned in order to only surface provider.locations that have the given organization(s) in the provider.locations.organizations field.

See the example response section below for more details

Example Request - Providers

Below is an example request to search for all providers who have an affiliation to Mount Sinai Health System within a 30 mile radius of NYC.

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/providers?location_organization_ids=497a1ac1-52cc-43a9-b796-844dabde10fc&distance=30&address=nyc' \
  -H 'authorization: Token <your_token>'

Example Response - Providers

Below is the example response for this request, which shows roughly 7K providers. As shown below, there are two fields within each provider object that contain organization affiliations - provider.organizations, which indicates all of the organizations that the provider is affiliated with, and provider.location.organizations, which indicates all of the organizations that the listed location is affiliated with.

It is important to note that provider.organizations is not always at 100% parity with all of the organizations listed across the provider.location.organizations fields. This is expected and is a result of Ribbon's methodology which aims to surface only the organizations that a provider is currently affiliated with and not a full historical view of the provider's past affiliations.

{
  "parameters": {
    "page": 1,
    "page_size": 25,
    "total_count": 6954,
    "sort_by": "distance",
    "address": "New York, NY, USA",
    "distance": 30,
    "geo": {
      "latitude": 40.7127753,
      "longitude": -74.0059728
    },
    "location_organization_ids": [
      "497a1ac1-52cc-43a9-b796-844dabde10fc"
    ]
  },
  "data": [
    {
      "npi": "1831164680",
      "first_name": "Ruben",
      "middle_name": "E",
      "last_name": "Olmedo",
      "status": "active",
      "age": 57,
      "gender": "m",
      "ratings_count": 0,
      "ratings_avg": null,
      "degrees": [
        "MD"
      ],
      "educations": [],
      "is_pcp": false,
      "specialties": [],
      "provider_types": [],
      "languages": [],
      "organizations": [
        {
          "uuid": "497a1ac1-52cc-43a9-b796-844dabde10fc",
          "name": "Mount Sinai Health System",
          "organization_types": [
            "Health System"
          ],
          "websites": [
            {
              "url": "https://www.mountsinai.org/"
            }
          ],
          "ids": [],
          "address": "1 Gustave L. Levy Pl, New York, NY 10029, US",
          "address_details": {
            "zip": "10029",
            "city": "New York",
            "state": "NY",
            "street": "1 Gustave L. Levy Pl",
            "address_line_1": "1 Gustave L. Levy Pl",
            "address_line_2": null
          },
          "phone_numbers": [
            {
              "phone": "2126598888",
              "detail": "primary"
            }
          ]
        }
      ],
      "insurances": [],
      "locations": [
        {
          "name": "Mount Sinai Doctors – Brooklyn Heights",
          "uuid": "120dbc0a-f73e-47b1-aaae-612077f9938b",
          "faxes": [],
          "address": "300 Cadman Plaza W FL 18, Brooklyn, NY 11201, US",
          "confidence": 2,
          "insurances": [],
          "organizations": [
            {
              "uuid": "497a1ac1-52cc-43a9-b796-844dabde10fc",
              "name": "Mount Sinai Health System",
              "organization_types": [
                "Health System"
              ],
              "websites": [
                {
                  "url": "https://www.mountsinai.org/"
                }
              ],
              "ids": [],
              "address": "1 Gustave L. Levy Pl, New York, NY 10029, US",
              "address_details": {
                "zip": "10029",
                "city": "New York",
                "state": "NY",
                "street": "1 Gustave L. Levy Pl",
                "address_line_1": "1 Gustave L. Levy Pl",
                "address_line_2": null
              },
              "phone_numbers": [
                {
                  "phone": "2126598888",
                  "detail": "primary"
                }
              ]
            }
          ],
          "phone_numbers": [
            {
              "phone": "9292106000",
              "details": "primary"
            },
            {
              "phone": "9292106110",
              "details": "secondary"
            }
          ],
          "location_types": [
            "Independent Clinic",
            "Imaging Center"
          ],
          "address_details": {
            "zip": "11201",
            "city": "Brooklyn",
            "state": "NY",
            "street": "300 Cadman Plaza W FL 18",
            "address_line_1": "300 Cadman Plaza W",
            "address_line_2": "FL 18"
          }
          ]
        }
      ]
    },...6953 more providers...
  ]
}