> ## Documentation Index
> Fetch the complete documentation index at: https://docs.carewithemma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Patient Journey Tools

> The tools Emma calls mid-conversation to register a new patient and handle billing questions

These aren't called from your own app — Vapi's voice agent calls them directly, in real time, while Emma is on the phone with a new patient walking through registration. They're part of the same sandbox data as the FHIR facade above, so anything a caller gives Emma over the phone shows up immediately if you look the patient up through Patient/\$match.

<Warning>
  Authentication here is different from every other page in this reference. There's no dashboard JWT — a phone call has no logged-in user. Every request instead carries a shared secret in an x-vapi-secret header, checked against Emma's server-side webhook secret (one shared value, not per clinic). Which patient and clinic a call belongs to is resolved on the server from the call's own metadata, never from anything in the request body.
</Warning>

## Request shape

Every tool is the same route with a different toolName, and Vapi can batch more than one tool call into a single request — so the response always echoes back one result per call, matched by toolCallId.

```text theme={null}
POST /patient-journey/:toolName
```

```json Request theme={null}
{ "message": { "toolCalls": [ { "id": "call_abc123", "function": { "arguments": { "statedName": "Jordan Lee", "statedPhone": "+14085551234" } } } ] } }
```

```json Response theme={null}
{ "results": [ { "toolCallId": "call_abc123", "result": "{\"success\":true,\"patientType\":\"NEW\"}" } ] }
```

Each result is itself a JSON string — decode it to get the shape documented below for that tool.

## resolve\_patient\_identity

Checks whether the caller matches an existing patient at this clinic, by name or phone.

<ParamField body="statedName" type="string">
  The name the caller gave
</ParamField>

<ParamField body="statedPhone" type="string">
  The phone number the caller gave
</ParamField>

<ParamField body="statedDateOfBirth" type="string">
  Not currently used in the match — accepted for future use
</ParamField>

At least one of statedName or statedPhone is required.

```json Result theme={null}
{ "success": true, "patientType": "EXISTING" }
```

patientType is "NEW" or "EXISTING". A match never merges records mid-call — it's just recorded for staff to see later.

## update\_registration\_field

Saves one or more registration fields as the caller gives them — Emma calls this repeatedly through the conversation, not once at the end.

<ParamField body="firstName" type="string" />

<ParamField body="lastName" type="string" />

<ParamField body="phone" type="string" />

<ParamField body="email" type="string" />

<ParamField body="preferredLocation" type="string" />

<ParamField body="medicareStatus" type="string" />

<ParamField body="healthPlanName" type="string" />

<ParamField body="referralSource" type="string" />

<ParamField body="commsConsent" type="boolean" />

```json Result theme={null}
{ "success": true, "registrationStatus": "ACTION_REQUIRED", "missingFields": ["email", "commsConsent"] }
```

registrationStatus flips to "COMPLETE" once name, phone, email, and every field above are on file — that's also the moment the patient goes from a placeholder record to a real, visible one on your Patients list.

## submit\_insurance\_info

Passes the caller's insurance details to the clinic's insurance-verification system and records the outcome.

<ParamField body="payerName" type="string" required />

<ParamField body="memberId" type="string" required />

<ParamField body="groupId" type="string" />

<ParamField body="subscriberName" type="string" />

```json Result theme={null}
{ "success": true, "status": "VERIFIED", "copayCents": 3000 }
```

This tool relays a verification result — it doesn't decide eligibility itself. errorMessage is present when verification failed.

## record\_self\_pay\_decision

Records what the caller chose after being told about a self-pay price (a price Emma looks up via the Knowledge Base earlier in the call, not this tool).

<ParamField body="decision" type="string" required>
  "self\_pay\_continue" or "billing\_escalation"
</ParamField>

<ParamField body="selfPayPriceCents" type="number">
  The price Emma quoted, for the record
</ParamField>

```json Result theme={null}
{ "success": true }
```

## escalate\_billing

Bundles up everything known about the call so far, onto the patient's record for staff to pick up. It doesn't transfer the call itself; Emma still does that as a separate step.

<ParamField body="reason" type="string">
  Free-text reason for the escalation
</ParamField>

```json Result theme={null}
{ "success": true }
```