Connections

The Connections resource is the read-only EHR catalog. Use it to power your own facility-search UI before initializing a direct-mode PatientFlow.

Method	HTTP
`mb.connections.list(params?)`	`GET /connections`
`mb.connections.retrieve(id)`	`GET /connections/{id}`

The API path is /connections; the resource type on the wire is fhir_source. The SDK exposes both via the Connection type alias.

List

Cursor-paginated. Filter by q (case-insensitive substring match on name) or type (epic, cerner, athena, etc.).

server/routes/search-ehrs.ts

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

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

  const page = await mb.connections.list({ q: query, limit: 20 });
  return {
    data: page.data.map((c) => ({
      id: c.id,
      name: c.name,
      type: c.type,
      logo_url: c.logo_url,
    })),
  };
}

ehr-picker.tsx

import { useState } from "react";

export function EhrPicker({ onSelect }: { onSelect: (id: string) => void }) {
  const [results, setResults] = useState<Array<{ id: string; name: string }>>([]);

  async function search(query: string) {
    const response = await fetch(`/api/ehrs?q=${encodeURIComponent(query)}`);
    const { data } = await response.json();
    setResults(data);
  }

  return (
    <>
      <input onChange={(e) => search(e.target.value)} placeholder="Search EHRs" />
      <ul>
        {results.map((c) => (
          <li key={c.id}>
            <button onClick={() => onSelect(c.id)}>{c.name}</button>
          </li>
        ))}
      </ul>
    </>
  );
}

The full Connection shape includes fhir_base_url, portal_url, and logo_url in addition to id, name, and type. See Get a FHIR source for the field list.

Auto-Pagination

list returns a ListPromise<Connection>. Use .autoPagingIterator() to walk every page:

server/scripts/dump-catalog.ts

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

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

See Pagination for cursor mechanics.

Retrieve

Retrieve one EHR by id. The path id accepts either a fhirsrc_* public id or the raw fhir_base_url. Both resolve server-side.

server/routes/get-ehr.ts

const ehr = await mb.connections.retrieve("fhirsrc_epic_mychart");
// or
const ehr = await mb.connections.retrieve("https://fhir.epic.com/.../R4");

A 404 arrives as MedblocksNotFoundError.

Selecting In Direct Mode

Once the patient picks an EHR, hand the id to mb.patientFlow.init:

server/routes/start-direct.ts

const flow = await mb.patientFlow.init({
  patient_id: input.patientId,
  connection_id: input.connectionId,
  return_url: "https://app.example.com/connected",
});

Errors

Subclass	When
`MedblocksNotFoundError`	The id does not exist or is not visible to your organization.
`MedblocksInvalidRequestError`	`limit` out of range, malformed pagination cursor.

SDK · PatientFlow · Direct mode
SDK · Pagination
API · Direct Mode. REST-equivalent walkthrough.
Reference · List FHIR sources. Exact schema.

List

Auto-Pagination

Retrieve

Selecting In Direct Mode

Errors

Related

On this page