> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/platform-api/conversations/surfaces.md).

# Surfaces

Agent-generated data collection interfaces: SurfaceSpec, fields, channels, lifecycle, and submission handling.

Surfaces are agent-generated data collection interfaces delivered to patients through supported communication channels. Agents analyze entity state and data gaps in the [world model](https://docs.concurrence.com/developer-guide/platform-api/data-world-model.md), generate a `SurfaceSpec`, and the platform renders and delivers it. Submissions return as source-attributed world-model events; any later external delivery follows a separate connector policy.

{% hint style="info" %}
**Conceptual overview.** For the architecture, healthcare examples, and design rationale, see [Surfaces](https://docs.concurrence.com/channels/surfaces) in the conceptual docs.
{% endhint %}

## Voice Agent Surface Tools

A family of context graph tools allows voice agents to create and manage surfaces during live calls:

| Tool                           | Parameters                                                                                                                                      | Returns                                                                                                                                                           |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_surface`               | `entity_id` (required), `title` (required), `fields` (required, list), `description`, `channel`, `expires_in_hours`, `resource_type`, `context` | `surface_id`, `url`, `status`, `expires_at`                                                                                                                       |
| `create_surface_from_template` | `template_id` (required), `entity_id` (required)                                                                                                | `surface_id`, `url`, `status`, `prefilled_count`, `total_fields`. Resolves a form template against the patient's entity state, prefilling fields with known data. |
| `get_form_templates`           | optional `category`, `patient_type` filters                                                                                                     | Reusable form templates for the workspace                                                                                                                         |
| `deliver_surface`              | `surface_id` (required), `channel_address` (required: phone number or email)                                                                    | `surface_id`, `url`, `status`                                                                                                                                     |
| `check_surface_status`         | `surface_id` (required)                                                                                                                         | `surface_id`, `status`, `title`, `fields_count`, `entity_id`, `created_at`                                                                                        |
| `get_surface_progress`         | `surface_id` (required)                                                                                                                         | Field-level completion status (which fields are filled vs empty)                                                                                                  |
| `reshape_surface`              | `surface_id` (required)                                                                                                                         | New `surface_id` and `url` containing only the unfilled fields from an abandoned form                                                                             |
| `list_entity_surfaces`         | `entity_id` (required), `status` (optional filter)                                                                                              | `surfaces[]` (id, title, status, channel, created\_at), `count`                                                                                                   |
| `get_surface_insights`         | `entity_id` (required)                                                                                                                          | `entity_id`, `completion_rate`, `preferred_channel`, `total_surfaces`, `completed`, `pending_surfaces`, `recent_surfaces[]`                                       |
| `extract_surface_file_text`    | `surface_id` (required)                                                                                                                         | Readable text extracted from submitted PDF file fields                                                                                                            |

`get_surface_insights` queries the entity's surface analytics before creating new surfaces. Returns completion rate, preferred channel, and count of pending (unfinished) surfaces. Call this before `create_surface` to avoid surface fatigue: if a patient already has multiple pending surfaces or a low completion rate, the agent may choose to collect data verbally instead.

These tools proxy through the Platform API surface endpoints. Authentication uses the call's `agent_session` JWT, which is workspace-scoped, so surface operations are automatically isolated to the correct workspace.

All of these tools handle errors gracefully: if the Platform API is unreachable, the agent receives an error message rather than an exception, so it can continue the call.

## Permissions

Two scopes control surface access:

| Scope            | Grants                                                |
| ---------------- | ----------------------------------------------------- |
| `surfaces:read`  | View surface specs, submissions, and lifecycle status |
| `surfaces:write` | Generate new surface specs                            |

Both scopes are included in the `member` role by default. RBAC enforcement is applied on all surface CRUD routes (view, create, update, delete).

## Management API

### Create a Surface

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/surfaces" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

Pass `conversation_id` to tie a surface to the text conversation it is for. A surface the agent creates during a text conversation is tied to that conversation without it. In a web conversation, the patient's submission goes to the conversation's agent, which can answer it in the conversation even after the conversation has gone idle. The answer is added to the conversation's turns and sent on its [conversation-scoped event stream](https://docs.concurrence.com/developer-guide/platform-api/conversations/sse-events.md#scope-to-one-conversation). A poll doesn't return it. Delivery is best-effort, so read the surface's status when a workflow must confirm the submission.

### List Surfaces

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/surfaces" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get a Surface

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/surfaces/{surface\_id}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Update a Surface

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/surfaces/{surface\_id}" method="patch" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Archive a Surface

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/surfaces/{surface\_id}" method="delete" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### List Surfaces Pending Review

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/surfaces/review" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Approve a Surface

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/surfaces/{surface\_id}/approve" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Reject a Surface

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/surfaces/{surface\_id}/reject" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Reshape a Surface

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/surfaces/{surface\_id}/reshape" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

The optional body's `conversation_id` names the text conversation asking for the replacement, which then gets its submission. Without one, the replacement belongs to the original surface's conversation.

### Get Surface Progress

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/surfaces/{surface\_id}/progress" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Deliver a Surface

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/surfaces/{surface\_id}/deliver" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

The delivery endpoint sends the surface URL to the patient, marks the surface as `delivered`, writes an audit event, and publishes a `surface.delivered` SSE event for real-time dashboards.

**Delivery behavior**: email-shaped delivery targets are sent through the workspace's configured email transport (the surface must have been created with `channel='email'` and a bound `use_case_id`). The email body contains a short redirect link (`/s/f/{surface_id}`) that 302-redirects to the full signed token URL. Non-email, non-phone targets record a web handoff. Phone-number targets are rejected with `422`.

**Error responses**: the deliver endpoint returns `404` (surface not found), `409` (already delivered/completed/expired, or test surface), `422` (validation, including a rejected phone target), and `429` (rate limited). Email delivery additionally returns `503` when email transport is not configured.

**Lifecycle SSE events**: `surface.delivered`, `surface.opened`, `surface.submitted` are published in real time as they happen.

**Surface expiry**: Non-terminal surfaces (not yet completed) automatically expire after their configured TTL. Expired surfaces reject renders, submissions, and auto-saves.

## Channels

| Channel | Value   | Delivery Method                       |
| ------- | ------- | ------------------------------------- |
| Email   | `email` | Email with branded link               |
| Web     | `web`   | Direct link for portals or dashboards |

A surface's `channel` is `email` or `web`, on a surface and on an outreach rule. Any other value, including `sms`, returns `422`. The deliver endpoint emails the link to an email address and records any other address as a web handoff, where the agent gives the person the link. A phone number returns `422`.

## BrandingConfig

Visual branding applied to the patient-facing form. Can be set at workspace level (default for all surfaces) or per-surface (overrides workspace defaults).

### Get Workspace Branding

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/settings/branding" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Update Workspace Branding

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/settings/branding" method="put" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

When rendering a surface, the platform merges workspace branding with surface-level branding. Surface-level values take precedence. Changes to workspace branding are audit-logged.

## Lifecycle

<figure><img src="https://1651797362-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2YwM0LHtEGLt9S21OyC3%2Fuploads%2Fgit-blob-88d68c885ed51263d1985fba268b72636d07f570%2Fsurfaces-lifecycle-lavender.svg?alt=media" alt="A surface progresses from creation and any required review through delivery, opening, partial data, and completion. Expiration and archival are separate lifecycle outcomes."><figcaption><p>Review, expiration, and archival remain separate from completed submission.</p></figcaption></figure>

| Status         | Value            | Description                                            |
| -------------- | ---------------- | ------------------------------------------------------ |
| Created        | `created`        | Spec generated and stored                              |
| Pending review | `pending_review` | Surface awaiting field-engineer review before delivery |
| Delivered      | `delivered`      | Sent to patient via channel                            |
| Opened         | `opened`         | Patient opened the link                                |
| Partial        | `partial`        | Some fields auto-saved                                 |
| Completed      | `completed`      | All required fields submitted                          |
| Expired        | `expired`        | TTL exceeded without completion                        |
| Archived       | `archived`       | Soft-deleted via the DELETE/archive route              |

## Data Flow

Submissions are written to the world model as events:

* **Source**: `surface` (distinguishable from EHR, voice, or manual imports)
* **Confidence**: Initial confidence level for patient-reported data
* **Entity**: Emitted lifecycle events carry the surface's `entity_id`, allowing supported world-model projections and timelines to associate them with that entity

When a patient submits a surface, the platform first commits the surface row as completed. It then schedules `surface.submitted` world-event emission asynchronously on a best-effort path. Timeline and entity projection updates therefore happen separately and can lag the successful submission response; an emission failure is logged rather than rolling back the committed surface.

An emitted surface event retains source provenance and confidence. Any later entity resolution or typed projection depends on the downstream pipeline for that event shape rather than a universal synchronous rule.

## Patient-Facing Endpoints

Patients access surfaces through HMAC-signed URL tokens. No login or account is required, and each token grants access to one specific surface.

### Open a Short Surface Link

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/s/f/{surface\_id}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Render a Surface

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/s/{token}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Submit a Surface

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/s/{token}/submit" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Save a Surface Field

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/s/{token}/fields/{key}" method="put" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

The short-link operation issues a redirect to a fresh signed-token URL and reports missing or expired surfaces separately. Rendering marks the surface as opened. Submission commits the completed surface before scheduling best-effort world-event publication. Field saves update the lifecycle to partial.

**Token format**: HMAC-SHA256 signed with a configured secret. Contains surface ID and expiration. Validated on every request.

**Rate limiting** (per IP):

* Render: 30 requests/minute
* Submit: 10 requests/minute
* Auto-save: 30 requests/minute

**Field value validation**: Individual field values are capped at 10KB to prevent payload abuse.

**Rendering**: server-side HTML generation for all 14 field types. Mobile-first, XSS-safe. Photo and file uploads use native device capabilities. Signature fields use touch input.

**Lifecycle concurrency**: each status update is committed against the surface row. Submission locks the row while checking terminal state and marking it completed, which rejects a competing repeat submission. World-event emission is outside that transaction.

When creating a surface via the management API, the response includes the signed `token` and full `url` if the token secret is configured.

### Get a Surface Spec

Returns the surface specification as JSON for the forms app, including saved field values and merged branding. The first access records a `surface.opened` event. The route is token-authenticated and takes no Bearer credential.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/s/{token}/spec" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Look Up Reference Data

Searches healthcare reference data to autocomplete a form field. The `lookup_type` path value selects medication, allergy, pharmacy, or insurance data. The route is token-authenticated and takes no Bearer credential.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/s/{token}/lookup/{lookup\_type}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Correct a Field Value

Applies a best-effort model correction to a form field value. When inference is unavailable or fails, the response returns the original value with confidence 0. The route is token-authenticated and takes no Bearer credential.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/s/{token}/heal" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Extract Insurance Card Fields

Reads insurance card fields from a photo and returns the requested fields the photo shows, with the lowest confidence across them. The request returns 422 when `image` is not a PNG, JPEG, WebP, or HEIC photo of at most 7 MB, and 502 when the model call fails. The route is token-authenticated and takes no Bearer credential.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/s/{token}/ocr" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get Appointment Availability

Returns free appointment slots for the surface's workspace within the requested date range, read from Slot resources in the entity projection. Use it to let a patient pick a slot inside a surface. The route is token-authenticated and takes no Bearer credential.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/s/{token}/availability" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Request a Booking

Submits a booking request for a specific slot and writes a `booking.requested` event tied to the surface's entity. Use it after the patient picks a slot from the availability response. The route is token-authenticated and takes no Bearer credential.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/s/{token}/book" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Form Templates

Form templates are workspace-level definitions that agents resolve into a surface. Reads require an authenticated caller in the workspace.

### List Form Templates

Lists all form templates for the workspace.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/settings/form-templates" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Replace Form Templates

Replaces all form templates for the workspace with the submitted list.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/settings/form-templates" method="put" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Resolve a Form Template

Resolves a template with prefill values from entity state and returns a hydrated surface spec ready to pass to surface creation. Fields with matching entity data carry `prefill_value`. For returning-patient templates, completed optional fields are removed.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/settings/form-templates/{template\_id}/resolve" method="post" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Outreach Settings

Outreach settings hold the workspace's outreach rules and data templates. They are stored configuration. A saved rule does not by itself establish that a message is delivered or that the recipient consented.

### Get Outreach Settings

Returns the workspace outreach settings, or empty rules and templates when none are configured. Any authenticated role can read them.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/settings/outreach" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Update Outreach Settings

Updates the workspace outreach settings. Partial updates are supported, and the `rules` and `data_templates` lists are replaced entirely when provided. The request is rejected when a rule's `data_template_id` points to a template that is in neither the payload nor the current settings. Requires the admin or owner role.

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/settings/outreach" method="put" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Surface Analytics

These workspace-scoped operations provide closed-loop optimization data and require viewer-or-higher permissions.

### Get Surface Completion Rates

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/analytics/surfaces/completion-rates" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get Surface Channel Effectiveness

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/analytics/surfaces/channel-effectiveness" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get Surface Field Abandonment

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/analytics/surfaces/field-abandonment" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

### Get an Entity's Surface History

{% openapi src="<https://platform.api-us.concurrence.com/v1/openapi.json>" path="/v1/{workspace\_id}/analytics/surfaces/entity/{entity\_id}" method="get" %}
<https://platform.api-us.concurrence.com/v1/openapi.json>
{% endopenapi %}

## Entity Type

Surfaces introduce the `interaction` entity type to the world model ontology. Surface lifecycle events (created, delivered, opened, submitted) are tracked as first-class entities with full event sourcing.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/developer-guide/platform-api/conversations/surfaces.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
