Guides
Start typing to search…

Search & Establish Data Connections

Application APIs

This workflow demonstrates how to search for healthcare providers, practices, and insurance companies, then establish secure data connections to retrieve patient health records. You'll use the SearchHealthResources query to find available data sources by keyword (such as "Sandbox Health System" or "Dr. Smith"), then initiate an OAuth connection flow to grant access to the user's health data from that source.

Prerequisites

  • health.network - This workflow requires health.network to be enabled for access to b.well's Patient Access API connections.
  • End-User Authentication - User must be authenticated with the health.network scope
  • Account Creation and Consent - User account and consent must be completed

Environment URL:

  • Client-Sandbox: https://api.client-sandbox.icanbwell.com/v1/graphql

Workflow Steps

Step 1: Search for Healthcare Resources by Keyword

Use the SearchHealthResources GraphQL query to search for healthcare providers, practices, or insurance companies by keyword, location, or other criteria. The query returns connection endpoint details needed to establish data access.

Common search patterns:

  • By keyword: Search for "Sandbox Health", "West Coast Health Clinic", or "UnitedHealthcare"
  • By location: Filter results by geographic coordinates or zip code
  • By type: Limit results to practices, individual practitioners, or insurance companies

Example GraphQL Query:

query SearchHealthResources($searchInput: SearchHealthResourcesInput) {
  searchHealthResources(searchInput: $searchInput) {
    pagingInfo {
      pageNumber
      pageSize
      totalItems
      totalPages
    }
    results {
      type
      id
      content
      location {
        name
        address {
          line
          city
          state
          postalCode
          country
        }
        position {
          latitude
          longitude
        }
        distanceInMiles
      }
      organization {
        name
        endpoint {
          name
        }
      }
      partOf {
        id
        content
        endpointName
      }
      npi
      gender
      endpoint {
        name
      }
    }
  }
}

Example Variables:

This example searches for "Sandbox Health" near Sacramento, CA, filtering for practices, practitioners, and insurance companies with available data connections.

{
  "searchInput": {
    "search": "sutter health",
    "searchLocation": {
      "lat": 38.5712412,
      "lon": -121.4802025,
      "zipCode": 10011
    },
    "filters": {
      "includePopulatedProaOnly": true,
      "type": [
        "PRACTICE",
        "PRACTITIONER",
        "INSURANCE"
      ]
    },
    "orderBy": [
      {
        "field": "RELEVANCE",
        "order": "DESC"
      }
    ],
    "paging": {
      "pageNumber": 0,
      "pageSize": 15
    },
    "client": [
      {
        "dataSets": [
          "CONNECTHUB",
          "NPPES"
        ],
        "config": "client_config"
      }
    ]
  }
}

Key Parameters:

  • search: Keyword to search for (provider name, practice name, insurance company)
  • searchLocation: Geographic filtering by latitude/longitude or zip code (preference given to lat/lon if both provided)
  • filters.type: Resource types to include (PRACTICE, PRACTITIONER, INSURANCE)
  • filters.includePopulatedProaOnly: Only return results with active data connection endpoints paging: Control result pagination

Step 2: Extract Connection Endpoint Details

From the SearchHealthResources response, extract the endpoint.name value which serves as the connectionId for initiating the OAuth connection flow.

Scenario 1: Endpoint in Main Result

If the result includes an endpoint array at the top level, extract the endpoint.name directly.

Example Response:

{
  "type": "PRACTICE",
  "content": "Johns Hopkins Medicine",
  "location": [
    {
      "name": "Johns Hopkins Medicine",
      "address": {
        "line": [
          "1650 Orleans St"
        ],
        "city": "Baltimore",
        "state": "MD",
        "postalCode": "21287"
      }
    }
  ],
  "partOf": null,
  "endpoint": [
    {
      "name": "example_endpoint_name"
    }
  ]
}

In this example, extract "example_endpoint_name" from endpoint[].name to use as the connectionId.


Scenario 2: Endpoint in Organization Array

If the main result does not include an endpoint, check the organization array. Organizations may contain their own endpoint.name values.

{
  "data": {
    "searchHealthResources": {
      "results": [
        {
          "type": "PRACTITIONER",
          "content": "MICHAEL PODLONE",
          "organization": [
            {
              "name": "BWell PROA Demo",
              "endpoint": [
                {
                  "name": "proa_demo"
                }
              ]
            }
          ],
          "npi": ["1497761985"],
          "endpoint": []
        }
      ]
    }
  }
}

In this example, extract "proa_demo" from organization[].endpoint[].name to to use as the connectionId.


Scenario 3: Endpoint in partOf Array

If the result is of type PRACTICE and includes a populated partOf array, the endpoint may be referenced through the parent organization relationship. Results with partOf set to null represent parent organizations, while results with a populated partOf array are child entities (such as individual clinic locations) that inherit their data connection from the parent.

{
  "type": "PRACTICE",
  "content": "Johns Hopkins Hospital",
  "location": [
    {
      "name": "Johns Hopkins Hospital",
      "address": {
        "line": [
          "600 N Wolfe St"
        ],
        "city": "Baltimore",
        "state": "MD",
        "postalCode": "21287"
      }
    }
  ],
  "partOf": {
    "id": "8d56a14d-65ee-59f6-ba83-90c96ad681e4",
    "content": "Johns Hopkins Medicine",
    "endpointName": "example_endpoint_name"
  },
  "endpoint": [
    {
      "name": "example_endpoint_name"
    }
  ]
}

In this example, extract "example_endpoint_name" from either partOf[].endpointName or endpoint[].name to use as the connectionId.

Since all child organizations share the same endpoint as their parent organization, you can use the values within the partOf array to group related results together in your UI. This allows you to display a single parent organization (e.g. "Johns Hopkins Medicine") with nested child results underneath, improving the user experience by reducing duplicate endpoint entries and providing organizational context.


Step 3: Retrieve OAuth Authorization URL

Using the endpoint.name extracted in Step 2 as the connectionId, query getOauthUrl to retrieve the OAuth authorization URL for the selected healthcare provider.

query getOauthUrl($connectionId: String!) {
  getOauthUrl(connectionId: $connectionId) {
    redirectUrl
  }
}

Example Variables:

{
  "connectionId": "proa_demo"
}

Example Response:

{
  "data": {
    "getOauthUrl": {
      "redirectUrl": "https://auth.provider.com/oauth/authorize?client_id=..."
    }
  }
}

Step 4: Launch Authentication Flow

Direct the user to the redirectUrl returned by getOauthUrl. This URL initiates the OAuth authentication flow where the user securely logs into their healthcare provider's portal and authorizes b.well to access their health records.

Once the user completes the OAuth flow, they will be redirected back to your application. See the OAuth Connection Flow Guide for detailed implementation options for handling OAuth completion, including postMessage listeners, URL polling, and custom redirect URLs..


Updated 8 days ago

What’s Next