Searching Health Resources

This guide describes the operations related to b.well directory of providers and available connections. The searchHealthResources method enables comprehensive searching across resource types within the b.well ecosystem. It allows users to find and retrieve information about healthcare providers, facilities, and support services, including practitioners, clinics, hospitals, health systems, insurance providers, and laboratories, and their organization logos from a single search.

Prerequisites

• Completed Authentication and Account Creation

Summary of Steps

1. Use searchHealthResources to find the desired Provider, Health System, Pharmacy, Insurance or Lab
2. Optionally, allow users to request a connection be added to the directory

Step 1: Search the b.well Directory for Health Resources

Use the searchHealthResources endpoint to search the b.well directory.

Search Parameters

• Search Term (String): Key filter for searches, applicable for names, specialties, locations, or addresses.
• Filters: Filters results based on organization type.

  • PRACTICE used for hospitals, clinics, and health system connections.

  • PRACTITIONER used for healthcare providers.

  • LABORATORY used for laboratory connections.

  • INSURANCE used for insurance provider connections.

  • PHARMACY used for pharmacy connections.
    
    ID: Only return search results included in the array of IDs.

    Include Populated PROA Only: Return only results that have PROA connections.

    Location: Sorts results by geographical location using latitude and longitude.

• Sort Options:
  • By default, results are sorted by relevance in descending (DESC) order when no sortBy value is specified.
    • The most relevant results have the highest score, so sorting by DESC is required to see the most relevant results first.
  • Available sorting options include:
    • Relevance (default)
    • Distance
    • Content
• Pagination:
  • page: Specifies the page number for results.
  • pageSize: Determines the number of results per page.

Organization and Health System Logos

Search results for health systems, practices, and other organizations can include a logo image for that organization. logoUrl is a string field holding a public URL that points to an organization's or health system's logo image, such as a hospital system's brand mark. Use it to help end users visually confirm they are connecting to the right organization in search results.

logoUrl is exposed as a plain, nullable string property on the top-level search result object and on each nested organization object.

The nested organization list is only populated when a result represents a practitioner with a known organization affiliation. For practices, insurance, laboratories, and other types, organization is empty — rely on the top-level logoUrl for those results.

Key understandings

• Public and unauthenticated. No credentials or extra headers are needed to fetch the image at the returned URL.
• Nullable. Not every organization has a logo yet. If an organization does not yet have a logo on file, logoUrl is returned as null — never an error, never a placeholder, never a broken-link URL.
• Additive. logoUrl is a new, optional field on existing search response types. You only receive it if you explicitly read the corresponding property. Existing integrations that don't reference it are unaffected. The field name is always camelCase — logoUrl, never logo_url.

Your integration should always:

• Treat logoUrl as optional and nullable in your data model.
• Render your own local placeholder — a generic building or organization icon, an initial-based avatar — whenever logoUrl is null.
• Check for null before assuming a value is present.

Example

import { SearchHealthResourcesRequest } from "@icanbwell/bwell-sdk-ts";
 
const response = await sdk.search.searchHealthResources(
  new SearchHealthResourcesRequest({
    search: "cardiologist",
    searchLocation: { zipCode: "10001" },
  })
);
 
for (const result of response.data?.results ?? []) {
  // result.logoUrl: string | null
  const logo = result.logoUrl ?? "/assets/placeholder-logo.png";
 
  // Nested organization logos are also available:
  const orgLogo = result.organization?.[0]?.logoUrl ?? null;
}

Rendering best practices

• Don't send credentials. The URL can be fetched with a standard image request. Do not attach API credentials to it.
• Always have a placeholder. Ship a default placeholder image or icon in your app and show it whenever logoUrl is null.
• Prefer the most specific logo available. When both a result-level logoUrl and a nested organization logo are present, prefer the most specific one for that result. Fall back to the parent organization's logo when the result's own logoUrl is null.

Quick reference

Step 2: Submit a Connection for Review

In cases where the user is unable to find their desired connection, they can submit a request to the b.well team. The b.well team will attempt to add the requested connection to the b.well directory.

For this use case, use submitProviderForReview. Based on client configuration, the user may be notified of the availability of the connection via email or other notification system.

For complete request and response schema, see SearchManager documentation.