Skip to main content
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.
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.

​
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.
Request
Response
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.
​
string
The name the caller gave
​
string
The phone number the caller gave
​
string
Not currently used in the match — accepted for future use
At least one of statedName or statedPhone is required.
Result
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.
​
string
​
string
​
string
​
string
​
string
​
string
​
string
​
string
​
boolean
Result
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.
​
string
required
​
string
required
​
string
​
string
Result
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).
​
string
required
“self_pay_continue” or “billing_escalation”
​
number
The price Emma quoted, for the record
Result

​
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.
​
string
Free-text reason for the escalation
Result