Health Records Tools - Arlo Health

Overview

get_health_records is a read-only view over the patient’s connected insurance and health records, sourced from their insurer via Flexpa (flattened SQL-on-FHIR views). It never connects, refreshes, or mutates anything. Connecting is a separate pair of tools, because the Flexpa Link flow runs in the user’s browser:

Situation	What to call
The user is already onboarded and wants to connect, change, or reconnect records	`start_flexpa_link`, then poll `complete_flexpa_import`
The user is still in setup (`onboardingComplete: false`) and the onboarding widget is open	Let the widget drive the connection

Records are optional — care works without them, so never block a consultation on connecting.

get_user_profile already carries a healthRecords block — connection + sync state and per-category record counts (no record contents) — so you can tell whether records exist, and whether reading them is worthwhile, without calling get_health_records.

Connected insurance also powers the care pricing tools — plan matching for search_care_prices and check_network_status resolves from the linked coverage automatically.

get_health_records

Parameters

Parameter	Type	Required	Description
`section`	string	No	Which area to read (default `summary`)
`offset`	number	No	Paging offset within a section, from a previous response’s `nextOffset`

Start with the summary

Call with no arguments first. section: "summary" returns the connection status, the insurance coverage header, basic demographics, and a count of records in each category — a cheap overview so you know what’s worth pulling before drilling in.

Sections

Section	Contents
`summary`	Connection status, coverage header, demographics, per-category counts
`coverage`	Insurance plan: payer, member/subscriber, plan period, pharmacy benefit IDs (RxBIN/RxPCN/RxGroup), cost-sharing
`conditions`	Problem/diagnosis list
`medications`	Prescribed / reported / dispensed medications
`allergies`	Allergies and reactions
`immunizations`	Immunization history
`labs`	Lab results (observations categorized `laboratory`, plus diagnostic reports)
`vitals`	Vital signs (heart rate, blood pressure, respiratory rate, …)
`visits`	Encounters and procedures
`claims`	Claims headers, diagnoses, procedures, and line items
`everything`	All of the above (large — prefer targeted sections)

Labs and vitals are split deliberately: in FHIR both are Observation resources, and a patient can have thousands of vital-sign readings. The split keeps recent labs from being buried behind vitals.

Paging

Each underlying view returns at most 100 rows per call, sorted newest-first so the cap keeps the most recent records. When a view is truncated, the response includes truncated: true, showing, and nextOffset — pass nextOffset back as offset to get the next page.

Returns (summary example)

{
  "section": "summary",
  "connection": {
    "payer": "Blue Shield of California",
    "importedAt": "2026-06-02T15:04:11.000Z",
    "lastSyncedAt": "2026-07-28T09:12:40.000Z",
    "syncStatus": "complete",
    "syncInProgress": false
  },
  "demographics": { "name": "John Doe", "birthDate": "1990-03-15" },
  "coverage": { "count": 1, "rows": [ { "payor": "Blue Shield of California", "...": "..." } ] },
  "recordCounts": {
    "coverage": 1,
    "conditions": 4,
    "medications": 12,
    "allergies": 1,
    "immunizations": 8,
    "labs": 61,
    "vitals": 340,
    "visits": 23,
    "claims": 47
  },
  "note": "Pass a section to drill into one area."
}

When no insurance is connected the response is { "connected": false, "message": ..., "howToConnect": ..., "nextStep": "start_flexpa_link" }. Each section returns one or more view blocks keyed by view name (for example coverage, problems, medication_request, allergies, immunizations, encounters, claims_header; labResults for labs and vitalSigns for vitals), all sharing the capped-view shape { count, truncated?, showing?, offset?, nextOffset?, rows[] }. count is the true total even when rows were capped.

Example flow

// 1. Cheap overview
const summary = await getHealthRecords();

// 2. Drill into what matters for the current question
if (summary.recordCounts.medications > 0) {
  const meds = await getHealthRecords({ section: "medications" });
}

// 3. Page through a long history when needed
let labs = await getHealthRecords({ section: "labs" });
while (labs.labResults?.nextOffset) {
  labs = await getHealthRecords({ section: "labs", offset: labs.labResults.nextOffset });
}

start_flexpa_link

Start a records connection so triage and providers see the patient’s real coverage, conditions, medications, allergies, and labs instead of asking for them. Returns an authorizationUrl for the user to open in their browser.

When to call

get_health_records reports connected: false and the user wants to connect
The user asks to add, change, or reconnect their insurance or health records

This is the records-only path and works for already-onboarded users. start_onboarding covers accounts that haven’t finished setup; while that widget is open, let it drive the connection instead.

Parameters

Parameter	Type	Required	Description
`ial2Mode`	boolean	No	`true` = TEFCA nationwide record discovery (CLEAR/ID.me identity verification). Omit or `false` = insurer / provider-portal login
`patientId`	string	No	Patient to connect records for (defaults to the primary patient)

Returns

{
  "authorizationUrl": "https://link.flexpa.com/...",
  "linkNonce": "nonce_abc123",
  "notice": "Connecting imports your coverage, conditions, medications, allergies, labs, and claims from your insurer. Arlo uses them only to give your clinicians context; they are never sold or used for advertising. Privacy Policy: https://arlohealth.ai/privacy",
  "nextStep": "Give the user authorizationUrl to open in their browser, then poll complete_flexpa_import with linkNonce until it stops returning pending."
}

Relay notice to the user in plain words before they open the link. It is the notice at collection for their records: what connecting imports, that it is only used to give their clinicians context, and where the Privacy Policy is. Don’t skip it.

The user can also connect from the Arlo patient portal. Hand over authorizationUrl when you want them to stay in the conversation.

complete_flexpa_import

Poll for the outcome of a connection started with start_flexpa_link. Call it every 10–15 seconds, or when the user says they’re done, until it returns something other than pending.

Parameters

Parameter	Type	Required	Description
`linkNonce`	string	Yes	The `linkNonce` from `start_flexpa_link`

Returns

Status	Meaning
`pending`	The user hasn’t finished at their insurer yet — poll again
`imported`	Connected. `complete: true` means the identity core (name, DOB, gender) is already on the profile; `syncing: true` means the clinical sync is still running, so `get_health_records` fills in shortly after
`cancelled`	The user declined or errored at Flexpa — offer a fresh `start_flexpa_link`
`failed`	The exchange or registration failed — offer a fresh `start_flexpa_link`
`expired`	The link session timed out — start over with `start_flexpa_link`

{
  "status": "imported",
  "complete": true,
  "syncing": true
}

​Overview

​get_health_records

​Parameters

​Start with the summary

​Sections

​Paging

​Returns (summary example)

​Example flow

​start_flexpa_link

​When to call

​Parameters

​Returns

​complete_flexpa_import

​Parameters

​Returns

Overview

get_health_records

Parameters

Start with the summary

Sections

Paging

Returns (summary example)

Example flow

start_flexpa_link

When to call

Parameters

Returns

complete_flexpa_import

Parameters

Returns