Onboarding Tools - Arlo Health

Overview

Onboarding tools manage user profiles and patient information required before care. The typical funnel is:

get_user_profile — check onboarding state and the computed nextStep
start_onboarding — open the interactive setup widget (preferred on widget-capable hosts)
update_patient_info — save demographics and medical history (data only)
accept_terms — record the patient’s explicit ToS/Privacy consent and complete onboarding

start_onboarding

Open the interactive Arlo onboarding widget. It walks the user through everything needed before care: importing their health records (nationwide TEFCA search or their insurer/provider portal) or entering details manually, reviewing demographics, accepting the Terms of Service, and saving a payment method.

When to call

get_user_profile shows onboardingComplete: false, or nextStep is update_patient_info / accept_terms / create_payment_setup
A new user needs to finish setting up their account

Parameters

None required.

Behavior

On widget-capable hosts, the widget renders alongside the tool result and drives the profile, terms, and payment steps itself.

While the widget is open, do not duplicate its flow in text — don’t ask the user for profile fields, and don’t call update_patient_info / accept_terms / create_payment_setup yourself; the widget drives those. Tell the user to complete setup in the card and call get_user_profile afterwards to confirm completion.

On clients that can’t render widgets, the tool instead returns an onboardingUrl into the Arlo patient portal — send the user that link, then poll get_user_profile until onboardingComplete.

Call start_onboarding only while onboardingComplete is false. An already-onboarded user who wants to connect or change health records uses start_flexpa_link instead.

get_user_profile

Get the current user’s Arlo Health profile and patient information: account status and billing state, patient profiles (self and dependents), the computed onboarding funnel state, and a healthRecords block showing whether insurance health records are connected and how many records exist.

Parameters

None required.

Returns

{
  "accountId": "acc_abc123",
  "status": "ONBOARDED",
  "billingMode": "PAY_AS_YOU_GO",
  "paymentStatus": "ACTIVE",
  "onboardingComplete": true,
  "missingFields": [],
  "nextStep": "ready",
  "regionSupported": true,
  "healthRecords": {
    "connected": true,
    "payer": "Blue Shield of California",
    "importedAt": "2026-06-02T15:04:11.000Z",
    "lastSyncedAt": "2026-07-28T09:12:40.000Z",
    "syncStatus": "complete",
    "syncInProgress": false,
    "hasRecords": true,
    "totalRecords": 187,
    "recordCounts": {
      "coverage": 3,
      "conditions": 8,
      "medications": 14,
      "allergies": 2,
      "immunizations": 6,
      "visits": 11,
      "claims": 96,
      "labs": 31,
      "vitals": 16
    },
    "nextStep": "get_health_records"
  },
  "patients": [
    {
      "patientId": "pat_xyz789",
      "firstName": "John",
      "lastName": "Doe",
      "birthDate": { "year": 1990, "month": 3, "day": 15 },
      "gender": "Male",
      "country": "US",
      "province": "CA",
      "isDefault": true,
      "medications": [],
      "conditions": [],
      "allergies": []
    }
  ]
}

Field	Description
`accountId`	The user’s account ID
`status`	`ONBOARDED`, `REGISTERED`, etc.
`billingMode`	`NONE`, `PAY_AS_YOU_GO`, `SUBSCRIPTION`, `LEGACY`
`paymentStatus`	`PENDING`, `ACTIVE`, etc.
`onboardingComplete`	Whether onboarding is done
`missingFields`	Required profile fields not yet saved
`nextStep`	The single next action to move this user toward care: `update_patient_info`, `accept_terms`, `create_payment_setup`, or `ready`
`patients`	Array of patient profiles (self or dependents)
`healthRecords`	Insurance / health-records connection state and record counts only — never record contents

Follow nextStep — it encodes the whole funnel, so you never need to re-derive what’s missing.

The `healthRecords` block

A pointer to the health records tools, not the data itself:

Field	Description
`connected`	`true` = insurance connected; `false` = nothing connected (offer `start_flexpa_link`); `null` = records service temporarily unreadable — never blocks care
`payer`	Connected insurer, when connected
`syncStatus` / `syncInProgress` / `syncNote`	Sync state; while `syncInProgress` is `true` the clinical import is still running and counts may grow. A `failed` sync means records may be missing or stale
`hasRecords` / `totalRecords`	Whether anything has been imported, and how much
`recordCounts`	Count per category (`conditions`, `medications`, `labs`, `vitals`, `claims`, …) — the same categories as `get_health_records` sections
`nextStep`	Records-specific: `start_flexpa_link` to connect, `get_health_records` to read what’s there. Independent of the top-level onboarding `nextStep` — records are optional and never gate care

When not connected, the block is { "connected": false, "message": ..., "howToConnect": ..., "nextStep": "start_flexpa_link" }.

Use healthRecords to decide whether calling get_health_records is worthwhile — it carries counts only, never the records themselves.

update_patient_info

Update patient information (demographics, contact, medical history). This is a data update only — it does not accept terms or complete onboarding. Once the required fields are filled, call accept_terms to finish.

Required Fields for Onboarding

Parameter	Type	Description
`firstName`	string	Patient’s first name
`lastName`	string	Patient’s last name
`birthDate`	object	`{ year, month, day }`
`gender`	string	`Female`, `Male`, or `Other`
`country`	string	`US` (or `CA` for legacy Canadian accounts)
`province`	string	State code for US patients (province code for Canadian ones)
`phone`	string	Required for US patients — US prescriptions are fulfilled by Photon Health via SMS

Optional Fields

Parameter	Type	Description
`patientId`	string	Patient ID to update (defaults to primary)
`displayName`	string	Preferred display name
`email`	string	Email address
`address`	string	Street address
`city`	string	City
`zip`	string	ZIP / postal code
`healthNumber`	string	Insurance member number (provincial health card for Canadian patients)

Medical History Fields

Parameter	Type	Description
`medications`	array	`[{ title, description }]`
`conditions`	array	`[{ title, description }]`
`allergies`	array	`[{ title, severity }]`
`replaceMedicalHistory`	boolean	Arrays are merged into the existing lists by default. Pass `true` with the full new list to replace instead (e.g. “I’m not taking those medications anymore”)

Example: Save Required Fields

{
  "firstName": "John",
  "lastName": "Doe",
  "birthDate": { "year": 1990, "month": 3, "day": 15 },
  "gender": "Male",
  "country": "US",
  "province": "CA",
  "phone": "+14155551234"
}

Example: Update Medical History

{
  "medications": [
    { "title": "Metformin", "description": "500mg twice daily" },
    { "title": "Lisinopril", "description": "10mg daily" }
  ],
  "conditions": [
    { "title": "Type 2 Diabetes", "description": "Diagnosed 2020" }
  ],
  "allergies": [
    { "title": "Penicillin", "severity": "severe" }
  ]
}

State and province codes

US: two-letter state codes (CA, NY, TX, …) plus DC Canada (legacy accounts): ON, BC, AB, SK, MB, QC, NB, NS, PE, NL, YT, NT, NU

The profile province is the patient’s home address. Care licensing is based on where the patient is physically located when they start a conversation — that’s the separate region parameter on start_conversation. A patient whose home province isn’t a care region can still get care while they are in one, so don’t use province to decide whether care is available.

accept_terms

Record the patient’s acceptance of Arlo’s Terms of Service and Privacy Policy and complete onboarding (account status → ONBOARDED).

This is a distinct consent step, separate from update_patient_info. Call it only after the user has explicitly agreed to the Terms of Service and Privacy Policy.

Preconditions

All required profile fields must already be saved via update_patient_info: firstName, lastName, birthDate, gender, country, province (and phone for US patients). If any are missing, the tool returns onboardingIncomplete with the list — fill them, then call accept_terms again.

Parameters

None.

Returns

{
  "success": true,
  "onboardingComplete": true,
  "status": "ONBOARDED",
  "billingMode": "PAY_AS_YOU_GO",
  "paymentStatus": "PENDING",
  "nextStep": "create_payment_setup"
}

Field	Description
`nextStep`	`create_payment_setup` = save a payment method next; `ready` = a usable payment method is already on file

​Overview

​start_onboarding

​When to call

​Parameters

​Behavior

​get_user_profile

​Parameters

​Returns

​The healthRecords block

​update_patient_info

​Required Fields for Onboarding

​Optional Fields

​Medical History Fields

​Example: Save Required Fields

​Example: Update Medical History

​State and province codes

​accept_terms

​Preconditions

​Parameters

​Returns

Overview

start_onboarding

When to call

Parameters

Behavior

get_user_profile

Parameters

Returns

The `healthRecords` block

update_patient_info

Required Fields for Onboarding

Optional Fields

Medical History Fields

Example: Save Required Fields

Example: Update Medical History

State and province codes

accept_terms

Preconditions

Parameters

Returns