Find connections

This is the first build step. Before a patient can connect their records, you need the connection they belong to. A connection is a catalog entry for one hospital, clinic, or payer (a health insurer). Medblocks keeps a catalog of these, and you search it to find the one the patient uses.

If you choose the Medblocks-hosted page, Medblocks renders this search for the patient. Use this page when you want to integrate the search functionality with your own UI.

Search the catalog

Search with mb.connections.list, passing the patient’s text as q. This is what powers the search box in your own UI, where the patient types their hospital’s name and picks it from the results. Your browser code never touches the Medblocks API directly, since your API key is a secret that lives only on your server. The browser calls a route on your server, and your server runs the search and returns the results.

import { mb } from "../medblocks";

export async function searchConnections(query: string) {
  if (query.trim().length < 2) return { data: [] };

  const page = await mb.connections.list({ q: query, limit: 20 });

  return {
    data: page.data.map((connection) => ({
      id: connection.id,
      name: connection.name,
      type: connection.type,
      logo_url: connection.logo_url,
    })),
  };
}

async function searchConnections(query: string) {
  if (query.trim().length < 2) return [];

  const response = await fetch(`/api/connections?q=${encodeURIComponent(query)}`);
  const { data } = await response.json();
  return data as Array<{ id: string; name: string; type: string | null }>;
}

q is a case-insensitive match on the connection’s name, and type narrows the results to one vendor, such as epic or cerner.

The screenshot below is an example from TrialMatched, a clinical trial matching app. TrialMatched asks patients to connect records from their hospitals so it can match them to relevant trials. In an app like that, this search box is where the patient finds the hospital or clinic they want to connect.

What a connection looks like

The API returns a page of connection results. A single result looks like this.

{
  "id": "fhirsrc_01J9YR9N3X4VZ6P2K5RH7M3LMP",
  "name": "Epic MyChart",
  "type": "epic",
  "fhir_base_url": "https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4",
  "logo_url": "https://cdn.medblocks.com/logos/epic.png",
  "portal_url": "https://www.mychart.com"
}

These are the fields you will usually render or store.

You only need id and name to build a working search experience. The rest is there to make it look right.

List or retrieve connections

Drop the q to walk the whole catalog, handy for caching it on your server. Call autoPagingIterator() and the SDK follows the pagination cursor for you, one page at a time.

for await (const connection of mb.connections.list({ limit: 100 }).autoPagingIterator()) {
  console.log(connection.id, connection.name);
}

Already know which connection you want? Pass mb.connections.retrieve either the connection ID or the fhir_base_url, since both resolve to the same entry. An ID that matches nothing throws a MedblocksNotFoundError.

const connection = await mb.connections.retrieve("fhirsrc_01J9YR9N3X4VZ6P2K5RH7M3LMP");

Next

Once the patient picks a connection, pass its id into a patient session. The patient goes to that facility’s patient portal to sign in and approve access. Your own UI shows how to wire the chosen connection into the session.

If you’d rather not run the search at all, a Medblocks-hosted page does it for you. The patient searches the catalog on the page you send them to.

Common errors

Read the full envelope and code list in Errors.

See also