> ## 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.
# Care Request Tools
> Propose real-world care actions that Arlo's care team executes after the patient approves
## Overview
A **care request** is an action your agent proposes on the patient's behalf that a person at Arlo carries out with another office: moving an external referral to a different clinic, booking an appointment, or cancelling and rescheduling one. The patient approves each request on a hosted sheet with their own verification, Arlo's care team executes it, and every step lands in an audit trail the patient can see.
Three tools cover it:
| Tool | Purpose |
| --------------------- | ---------------------------------------------------------------------------------- |
| `create_care_request` | Propose an action. Returns `pending_approval` and an `approvalUrl` for the patient |
| `get_care_request` | Poll one request's status and audit trail |
| `list_care_requests` | The account's requests, newest first |
**US patients only.** A request for a patient outside a supported region is refused with `REGION_NOT_SUPPORTED`. Do not retry.
### How approval works
* The agent only ever learns the **status** of a request, never an approval artifact. Approval happens on Arlo's page with the patient's own verification on their device, and cannot be completed by an agent. **Never open the `approvalUrl` yourself.**
* The approval **tier** is assigned server-side by action type. The agent does not choose it.
* Consent and authorizations are **per patient** within the account, and revocable per patient. The patient sees the same ledger, with revocation controls, on the care activity page of their Arlo portal.
* Approval links expire **15 minutes** after creation.
### The flow
Use the NPI from `search_care_prices` or `check_network_status` for the target provider, and names from `get_health_records` where they apply
Returns `status: "pending_approval"`, a `requestId`, and an `approvalUrl`
Say what will happen once they approve. On widget hosts (Claude.ai, ChatGPT) an approval card renders around the same link
Every 15 to 30 seconds, or when the user says they've decided, until `status` is `approved`, `declined`, or `expired`
On `approved`, Arlo's care team executes under a single-use grant. `status` moves to `executed` (or `failed`) and the `audit` trail records each step
***
## create\_care\_request
Propose a real-world care action for the user.
### Parameters
| Parameter | Type | Required | Description |
| ---------------- | ------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `actionType` | string | Yes | `move_referral`, `book_appointment`, or `cancel_or_reschedule` |
| `params` | object | Yes in practice | Structured, action-type-specific fields (below). Resolved server-side; the approval sheet never renders your prose as fact |
| `patientId` | string | No | Which patient on the account this is for (from `get_user_profile`). Omit for the default patient |
| `context` | string | No | A short plain-language reason. Shown on the approval sheet, attributed as the agent's note |
| `cost` | object | No | `{ amountCents, description }`. Only for cost-bearing actions. The sheet then also collects a payment hold, captured on completion |
| `idempotencyKey` | string | No | Agent runtimes only. See [safe retries](/mcp-tools/messaging#safe-retries-idempotency) |
### Naming the provider's office
Wherever an action points at a provider's office, **both the provider and the specific practice location are required**. Providers work at multiple locations, and the action is directed to one:
* **Identity**: `npi` (strongly preferred, so it resolves against Arlo's directory) or `providerName`
* **Location**: `city` and `state` (required), plus `facilityName`, `address`, and `phone` when known
### Action types
#### `move_referral`
For **external** referrals, written by an outside provider. Arlo does not hold the referral record; the care team confirms it with the source office before anything moves.
| `params` field | Description |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `specialty` | The referral's specialty |
| `referral.description` | **Required.** What the referral is for, as the patient describes it (for example "cardiology consult for palpitations") |
| `referral.writtenApprox` | When it was written, approximately |
| `referral.referenceNumber` | From the patient's paperwork. The strongest identifier |
| `source` | `{ providerName?, facilityName?, phone? }`. Who wrote it and where it sits now, exactly as the patient reports it |
| `target` | `{ npi \| providerName, city, state, facilityName?, address?, phone? }`. Where it should go |
| `appointmentLabel`, `estimates[]`, `savingsCents`, `openings` | Optional context shown on the sheet. `estimates` is `[{ label, amountCents }]` |
```json theme={null}
{
"actionType": "move_referral",
"params": {
"specialty": "Cardiology",
"referral": {
"description": "cardiology consult for palpitations",
"writtenApprox": "August 2026",
"referenceNumber": "REF-4471"
},
"source": {
"providerName": "Dr. Ana Ruiz",
"facilityName": "Bayview Family Medicine",
"phone": "+14155550140"
},
"target": {
"npi": "1234567893",
"city": "Oakland",
"state": "CA",
"facilityName": "East Bay Cardiology"
}
},
"context": "The patient wants an earlier appointment. East Bay Cardiology is in network on their plan and has openings next week."
}
```
#### `book_appointment`
| `params` field | Description |
| ------------------ | ----------------------------------------------------------------------- |
| `provider` | `{ npi \| providerName, city, state, facilityName?, address?, phone? }` |
| `specialty` | Optional |
| `appointmentLabel` | Optional, for example "New patient visit" |
| `reason` | Optional, the reason for the visit |
| `estimates` | Optional `[{ label, amountCents }]` |
#### `cancel_or_reschedule`
| `params` field | Description |
| ------------------ | ------------------------------------------------------------- |
| `appointmentLabel` | Which appointment |
| `provider` | `{ npi \| providerName, city, state, ... }` |
| `newTimeLabel` | Optional. The requested new time, as the patient describes it |
Records release, refills, claim disputes, and standing payment grants are **not available yet**. The server rejects them with `ACTION_NOT_AVAILABLE` and the currently available list. Do not offer them to the user.
### Returns
```json theme={null}
{
"status": "pending_approval",
"requestId": "req_abc123",
"actionType": "move_referral",
"tier": 2,
"approvalUrl": "https://patient.arlohealth.ai/care-approval?t=...",
"expiresAt": 1788525600,
"sheet": {
"title": "Move your cardiology referral",
"subtitle": "From Bayview Family Medicine to East Bay Cardiology, Oakland"
},
"agentInstructions": [
"Give the user the approvalUrl and ask them to review and approve it. Never open it or attempt to approve it yourself.",
"Poll get_care_request with this requestId (every ~15-30 seconds, or when the user says they've decided) until status is approved, declined, or expired.",
"The link expires 15 minutes after creation."
]
}
```
### Errors
| Code | Meaning |
| -------------------------------------------- | --------------------------------------------------------------------------- |
| `REGION_NOT_SUPPORTED` | The patient is not in a supported US region. Do not retry |
| `ACTION_NOT_AVAILABLE` | The action type is not executable yet. The payload lists the available ones |
| `UNSUPPORTED_ACTION_TYPE` / `MISSING_PARAMS` | Fix the call as reported and try again |
***
## get\_care\_request
Status of a care request plus the patient-visible audit trail. Widget hosts refresh the approval card through this tool too.
### Parameters
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------------------------------- |
| `requestId` | string | Yes | The `requestId` returned by `create_care_request` |
### Returns
```json theme={null}
{
"requestId": "req_abc123",
"actionType": "move_referral",
"tier": 2,
"status": "approved",
"sheet": {
"title": "Move your cardiology referral",
"subtitle": "From Bayview Family Medicine to East Bay Cardiology, Oakland"
},
"approvedViaLabel": "verified with your security code",
"grantId": "grant_def456",
"expiresAt": 1788525600,
"audit": [
{ "actor": "agent", "label": "Request created", "meta": null, "at": 1788524700 },
{ "actor": "patient", "label": "Approved", "meta": null, "at": 1788524880 },
{ "actor": "system", "label": "Care team notified", "meta": "execution queued with grant scope attached", "at": 1788524881 }
]
}
```
| Field | Description |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | `pending`, `approved`, `declined`, `expired`, `executed`, or `failed` |
| `approvalUrl` | Present only while `pending`. Hand to the user |
| `approvedViaLabel` | On approval: how the user verified, in the words the patient saw |
| `grantId` | On approval: the single-use grant the care team executes under |
| `audit[]` | `{ actor, label, meta, at }` entries. `actor` is `agent`, `patient`, a care-team member, or `system`. Entries are never edited; corrections are new entries |
### Statuses
| Status | Meaning |
| ---------- | ---------------------------------------------------------------------------------------- |
| `pending` | Waiting for the patient. `approvalUrl` is present |
| `approved` | The patient approved. Execution is queued |
| `declined` | The patient declined on the sheet |
| `expired` | The 15-minute approval window passed. Create a new request if the patient still wants it |
| `executed` | Arlo's care team completed the action |
| `failed` | Execution failed. The audit trail says why |
***
## list\_care\_requests
The user's care requests, newest first: pending approvals, approved actions in execution, and completed ones.
### Parameters
None.
### Returns
```json theme={null}
{
"requests": [
{
"requestId": "req_abc123",
"actionType": "move_referral",
"status": "pending",
"title": "Move your cardiology referral",
"subtitle": "From Bayview Family Medicine to East Bay Cardiology, Oakland",
"createdAt": 1788524700,
"approvedViaLabel": null,
"approvalUrl": "https://patient.arlohealth.ai/care-approval?t=..."
}
],
"count": 1
}
```
`approvalUrl` is present only while a request is pending.
## Related
Resolve the target provider's NPI and network status before proposing a move or a booking
The patient's coverage, conditions, and visits, for the context you attach to a request