> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arlohealth.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Onboarding Tools
> User profile, patient information, and account setup
## Overview
Onboarding tools manage user profiles and patient information required before care. The typical funnel is:
1. `get_user_profile` — check onboarding state and the computed `nextStep`
2. `start_onboarding` — open the interactive setup widget (preferred on widget-capable hosts)
3. `update_patient_info` — save demographics and medical history (data only)
4. `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`](/mcp-tools/health-records#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
```json theme={null}
{
"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](/mcp-tools/health-records), 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`](/mcp-tools/health-records#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
```json theme={null}
{
"firstName": "John",
"lastName": "Doe",
"birthDate": { "year": 1990, "month": 3, "day": 15 },
"gender": "Male",
"country": "US",
"province": "CA",
"phone": "+14155551234"
}
```
### Example: Update Medical History
```json theme={null}
{
"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
```json theme={null}
{
"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 |