Search Connections

Overview

search_connections searches for healthcare data source endpoints — providers, practices, practitioners, laboratories, pharmacies, and insurers — that a user can connect to in order to import their health records. Call this tool when the user wants to link or sync medical data from a provider, insurance plan, lab, or pharmacy. The endpoint names in the results are intended to be passed to the connect_to_datasource tool to initiate an OAuth connection. If you have a ZIP code but no coordinates, call convert_zipcode_to_coordinates first (or pass the ZIP code directly via the zipcode parameter) to enable location-based ranking.

Required Parameters

search_text (string)

• Text query to search for providers, practices, or related healthcare entities.
• Example: "John Smith MD" or "pharmacy Baltimore".

Optional Parameters

lat (number)

• Default: 43.0744554
• Latitude for geographic filtering. If provided (along with lon), results are prioritized by proximity.
• If a zipcode is supplied and lat/lon are left at their defaults, omitted, or 0, the server geocodes the ZIP code and uses the resulting coordinates instead.

lon (number)

• Default: -89.3892675
• Longitude for geographic filtering. Used together with lat to sort results by distance.
• Subject to the same ZIP-code geocoding fallback described under lat.

include_populated_proa_only (boolean)

• Default: true
• When true, restricts results to providers with populated PROA (Point of Access) connections.

include_inactive (boolean)

• Default: true
• When true, includes inactive providers/endpoints in the results.

page_size (integer)

• Default: 10
• Number of results to return per page.

page_number (integer)

• Default: 0
• Page number of results to retrieve, 0-based.

zipcode (string)

• Default: null
• Backup to the convert_zipcode_to_coordinates tool — a ZIP code used for geographic filtering when coordinates are not supplied directly. Accepts numeric or string ZIP codes.

debug (boolean)

• Default: false
• Whether to include debugging information in the response.

Returns

A dictionary wrapping the underlying search_health_resources search result, with the following structure:

• paging_info — page_number, page_size, total_items, total_pages.
• filter_values — list of available filters, each with a field (e.g. COMMUNICATION, SPECIALTY, GENDER, CHARACTERISTIC, INSURANCE_PLAN) and its possible values (each with a value and a count).
• results — list of matched entities, each with:
  • type_ — one of PRACTICE, PRACTITIONER, INSURANCE, LABORATORY, PHARMACY.
  • id, content, gender, icon_string, score.
  • specialty — list of {code, system, display}.
  • location — list of {name, address: {line, city, state, postal_code, country}, position: {latitude, longitude}, telecom: [{system, value}], distance_in_miles}.
  • organization — list of {name, endpoint: [{name, status, address}]}.
  • npi — list of NPI identifiers.
  • endpoint — list of connectable endpoints, each with identifier (coded identifiers), name, status (ACTIVE, OFF, SUSPENDED, TEST, ERROR, ENTERED_IN_ERROR), connection_type ({code, system, display}), and address.
  • scores — list of {value, description, calculation} explaining how the result was ranked.

Notes

An endpoint's name field in the results[].endpoint list is the value to pass as endpoint_name to the connect_to_datasource tool to generate an OAuth connection URL for that data source.