Surfaces

Agent-generated data collection interfaces delivered to patients via SMS, WhatsApp, email, voice, or web - no form builders, no templates.

A patient calls to schedule an appointment. During the call, the agent realizes it needs insurance information and a photo of the insurance card. It cannot collect a photo over the phone. Instead of asking the patient to call back or visit a portal, the agent generates a surface - a short data collection form - and texts the patient a secure link before the call ends. The patient fills it out on their phone. The data flows back into the world model, passes through confidence gates and review, and is available for the next interaction.

Surfaces replace the gap between "we need this data" and "we have a way to collect it." They work across channels, are generated dynamically by agents based on what they know and what they need, and feed directly into the same data pipeline as every other source.

How Surfaces Work

The agent decides what to ask. The platform handles rendering, delivery, and collection. There are no templates or form builders - the agent generates the surface spec directly from its understanding of what data is missing.

Mid-Call Surface Tools

Voice agents have direct access to surfaces during live calls through four context graph tools. This means an agent can identify missing data during a conversation, create a form, and text the patient a link - all while still on the phone.

Tool	What It Does
Create surface	Agent specifies the entity, title, and fields it needs. Returns a signed URL for patient delivery.
Deliver surface	Records that the surface was sent to the patient (via SMS or read aloud). Triggers a lifecycle event.
Check status	Agent polls whether the patient has opened, partially filled, or completed the surface. Useful for real-time follow-up during the call.
List entity surfaces	Shows existing surfaces for the entity so the agent avoids sending duplicates. Filterable by status.

A typical mid-call flow: the agent notices the patient's insurance card is missing, creates a two-field surface (front photo + back photo), texts the link to the patient's phone, and checks back 30 seconds later to see if the patient has opened it. If completed before the call ends, the agent confirms receipt. If not, the surface stays active and the patient can complete it later.

Real-Time Surface Observation

The agent does not need to poll for completion. When a patient submits a surface during an active call, the agent is notified automatically and can acknowledge the submission in the conversation. For example: "I can see you just uploaded your insurance card - thank you, let me pull that up."

This works through the same real-time event stream that powers the dashboard. The voice agent subscribes to workspace events during the call and filters for surface submissions matching surfaces it created. The notification is injected into the conversation as guidance, so the agent responds naturally without interrupting the current flow.

These tools are available as context graph actions within any HSM state. Authentication uses the call's session credentials, so surface operations are automatically scoped to the correct workspace.

Automated Gap Detection

Beyond mid-call surfaces, the platform can proactively identify missing data and create surfaces automatically. A background scanner periodically examines entity state across the workspace, compares it against configurable requirements, and creates surfaces for any gaps it finds.

For example: a workspace can define that every patient with an upcoming appointment must have insurance information, a pharmacy on file, and an emergency contact. The scanner checks all patient entities against these requirements, and for any patient with missing data, creates a surface and delivers it via SMS - days before the appointment, without any human or agent action.

Setting	What It Controls
Requirements	Named rules defining which fields must be present for an entity type (e.g., "insurance card required for patients with upcoming appointments")
Trigger	When to check - before upcoming appointments or after recent interactions
Channel	How to deliver the surface (SMS, email, etc.)
Cooldown	How long to wait before re-scanning the same entity (default 7 days, prevents notification fatigue)
Priority	Low, normal, or high - controls processing order

The scanner is rule-based with no LLM involvement. It runs on the connector runner as an additional background loop alongside the existing poll, reconciliation, and review loops. It is disabled by default and configured per workspace.

Auto-Delivery via Text Conversations

When the gap scanner creates an SMS surface and auto-delivery is enabled, it does not just send a bare link. Instead, it triggers an outbound text conversation - the same HSM-driven agent that handles voice calls now conducts a multi-turn SMS exchange with the patient. The surface is delivered inline within the conversation, giving the patient context about why they are being asked and the ability to ask questions. This replaces the previous model of sending a standalone SMS with a link and hoping the patient opens it.

Outreach Optimization

Surface analytics feed back into surface creation to prevent fatigue and improve completion rates. This closes the loop between "we sent a surface" and "did the patient actually fill it out."

Agent-side intelligence - Before creating a new surface during a call, the voice agent can query a patient's surface history: how many are pending, what their completion rate is, and which channel they prefer. If a patient already has three unfinished surfaces, the agent may decide to collect the data verbally instead. If a patient consistently completes SMS surfaces but ignores email, the agent uses SMS.

Gap scanner fatigue gating - The automated gap scanner respects per-workspace limits:

Setting	Default	What It Controls
Max pending surfaces	3	Skip entities that already have this many unfinished surfaces
Min completion rate	0%	Skip entities whose historical completion rate is below this threshold
Channel optimization	Off	When enabled, override the default channel with each entity's historically preferred channel

These settings prevent the common failure mode of automated outreach systems: sending more messages to patients who do not respond, which decreases engagement and increases opt-out rates.

Channels

Surfaces reach patients through the channels they already use:

Channel	How It Works	Best For
SMS	Text message with a secure link	Quick data collection, appointment prep
WhatsApp	WhatsApp message with a secure link	Regions where WhatsApp is primary
Email	Email with a branded link	Longer forms, document collection
Voice	IVR-style data collection during a live call	Simple confirmations, date/time selection
Web	Direct link for embedding in portals	Integration with existing patient portals

The agent selects the channel based on the patient's communication preferences and the nature of the request. A photo upload goes via SMS or email, not voice. A yes/no consent confirmation can happen on the call itself.

What Surfaces Can Collect

Twelve field types cover the range of healthcare data collection needs:

Type	Example Use
Text	Name, address, pharmacy name
Long text	Symptom description, special instructions
Date	Date of birth, preferred appointment date
Phone	Contact number, emergency contact
Email	Patient email for follow-up
Number	Age, weight, dosage amount
Single select	Preferred provider, insurance type
Multi select	Symptoms from a checklist, available days
Checkbox	Consent confirmation, HIPAA acknowledgment
Photo	Insurance card front/back, wound photo, ID
Signature	Digital consent signature, authorization
File	Referral letter, prior records, lab results

Fields support prefilling from known data (so patients do not re-enter information the system already has), conditional display (show a field only when another field has a specific value), and PHI flagging for sensitive data handling.

Lifecycle

Each surface progresses through a tracked lifecycle:

Status	What It Means
Created	Spec generated by agent, stored in world model
Delivered	Sent to patient via the chosen channel
Opened	Patient opened the link
Partial	Some fields submitted (auto-saved as patient progresses)
Completed	All required fields submitted
Expired	TTL exceeded without completion (default 7 days, configurable 1 hour to 1 year)

Data Flow

Surface submissions enter the world model through the same pipeline as every other data source:

• Source: surface - distinguishable from EHR, voice, or manual imports in analytics and audit trails

• Confidence: Initial confidence appropriate for patient-reported data - not automatically trusted at the same level as authoritative EHR data

• Entity association: All surface events (creation, delivery, submission) are linked to the specific entity the surface was generated for, so they appear in entity timelines and trigger entity state recomputation

When a patient submits a surface, the platform recomputes the entity's state within the same transaction. Submitted form data flows directly into the entity's demographic and clinical projections - there is no delay or background job between submission and the data being available for the next interaction.

This means surface data passes through the same confidence gates, review queues, and entity resolution as data from any other source. A photo of an insurance card uploaded via a surface goes through the same verification pipeline as insurance data extracted from a phone call.

Healthcare Examples

Scenario	What the Agent Generates
Pre-visit intake	After scheduling, send a surface with insurance card photo, pharmacy name, medication list, and consent signature
Post-call follow-up	After a triage call, text a surface with symptom tracker fields and a photo upload for the affected area
Insurance verification	During a call where insurance details are unclear, text a surface for front/back photos of the card
Consent collection	Before a referral, email a surface with a consent form, digital signature, and HIPAA acknowledgment
Appointment prep	Day before appointment, send a surface with transportation needs, interpreter request, and current medications

Delivery

When a surface is ready, it can be delivered to the patient via SMS with a single API call. The delivery endpoint sends the surface URL to the patient's phone number, records a lifecycle event, and publishes a real-time notification. Email and WhatsApp delivery follow the same pattern.

iOS Link Trust

iOS blocks clickable links in SMS messages from unknown senders. To work around this, SMS surface delivery uses a two-step process:

1. Contact card - A vCard attachment is sent first, prompting the patient to save the sender as a contact. The vCard includes the workspace's business name and phone number.

2. Form link - The surface URL is sent in a second message. Because the patient now has the sender saved as a contact, iOS renders the link as tappable.

If the contact card fails to deliver, the form link is still sent - the vCard step is best-effort. Patients on Android or other platforms receive the link normally regardless.

Short URLs

Surface links delivered via SMS use short redirect URLs instead of the full cryptographically-signed token URL. The short URL resolves server-side to the full surface page. This keeps SMS messages compact and prevents carriers from truncating or splitting messages that contain long URLs.

Other Delivery Methods

The agent can also read the URL aloud during a voice call for immediate access, or embed it in a follow-up message through any existing communication channel.

Real-time events (surface.delivered, surface.opened, surface.submitted) are published as they happen, so dashboards and agents can react to patient progress.

Patient Experience

Patients access surfaces through a secure link - no login, no app download, no account creation. The link contains a cryptographically signed token that grants access to that specific surface only.

The surface renders as a mobile-first HTML page that works on any device. All twelve field types render natively - photo uploads use the device camera, signatures use touch input, date pickers use the platform default. Fields auto-save as the patient progresses, so no data is lost if they close the browser and return later.

Rate limiting protects patient-facing endpoints against abuse without affecting the patient experience.

Security

• Token-based access - Patients access surfaces via HMAC-signed URL tokens. No login required. Each token grants access to one specific surface only.

• Scoped access - Dedicated surfaces:read and surfaces:write permissions control who can generate and view surfaces

• Sensitive fields - Fields flagged as sensitive receive additional PHI handling throughout the pipeline

• Expiration - Surfaces automatically expire after their configured TTL, limiting the exposure window

• Entity-scoped - Each surface is associated with a specific entity, maintaining workspace-level data isolation

• Rate limiting - Patient-facing endpoints are rate-limited per IP to prevent abuse

• Audit trail - Surface creation, delivery, and submission are recorded in the unified audit trail

Developer Guide - For model schemas, field definitions, and API details, see the Surfaces page in the developer guide.