Care Request Tools - Arlo Health

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

Build the request from Arlo's own data

Use the NPI from search_care_prices or check_network_status for the target provider, and names from get_health_records where they apply

Call create_care_request

Returns status: "pending_approval", a requestId, and an approvalUrl

Hand the approvalUrl to the user

Say what will happen once they approve. On widget hosts (Claude.ai, ChatGPT) an approval card renders around the same link

Poll get_care_request

Every 15 to 30 seconds, or when the user says they’ve decided, until status is approved, declined, or expired

Execution

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

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 }]`

{
  "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

{
  "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

{
  "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

{
  "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.

Care pricing

Resolve the target provider’s NPI and network status before proposing a move or a booking

Health records

The patient’s coverage, conditions, and visits, for the context you attach to a request

​Overview

​How approval works

​The flow

​create_care_request

​Parameters

​Naming the provider’s office

​Action types

​move_referral

​book_appointment

​cancel_or_reschedule

​Returns

​Errors

​get_care_request

​Parameters

​Returns

​Statuses

​list_care_requests

​Parameters

​Returns

​Related

Care pricing

Health records

Overview

How approval works

The flow

create_care_request

Parameters

Naming the provider’s office

Action types

`move_referral`

`book_appointment`

`cancel_or_reschedule`

Returns

Errors

get_care_request

Parameters

Returns

Statuses

list_care_requests

Parameters

Returns

Related