# Form links

> Send a person a link to a form during a call, watch them fill it in, and read what they submit.

Source: https://docs.vlayers.ai/developers/forms

Kind: How-to guide

> **Warning:** **Limited today.** Form links work with a fixed set of forms that VoiceLayer provides: `demo-intake` and `auto-damage-evidence`. You cannot add your own form through the API or the dashboard yet. Use this page if one of those fits, or to see how the feature works.

## What you'll build

A link to a short form, sent by text or email, that the person fills in on their phone while your agent is on the line. You see each field as it is set and the final submission.

## Prerequisites

- A secret API key with the `sdk:write` scope. See [Authentication and API keys](https://docs.vlayers.ai/get-started/authentication).
- To text the link, a phone number in your workspace (its id goes in `sendSms.phoneNumberId`) and a registered texting program. To email it, an address to send to.
- curl.

## Step 1: Create the form link

`POST /v1/forms` creates a session and, if you ask, sends the link. This route is not in the generated clients, so use curl.

```bash
curl -s https://api.vlayers.ai/v1/forms \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "formId": "demo-intake",
    "recipientPhone": "+15550123",
    "recipientName": "Ada Lovelace",
    "prefill": { "firstName": "Ada" },
    "ttlSeconds": 3600,
    "sendEmail": { "to": "ada@test.vlayers.ai", "subject": "Your intake form" }
  }'
```

- `formId` and `recipientPhone` (E.164) are required. `recipientName`, `prefill`, `webhookUrl`, `callbackFromNumber`, `sendSms` and `sendEmail` are optional.
- `ttlSeconds` is 60 seconds to 90 days. After that the link is `expired`.
- Set `sendSms` (`phoneNumberId`, optional `bodyPrefix`) or `sendEmail` (`to`, optional `subject` and `bodyPrefix`), or both. Set neither to get the link back and deliver it yourself.

```json
{
  "sessionId": "…",
  "token": "…",
  "url": "https://<your forms host>/f/<token>",
  "smsId": null,
  "emailId": "…",
  "expiresAt": "2026-11-04T16:04:05.000Z"
}
```

Anyone who has the `url` can read and fill the form, so send it only to the person it is for.

Errors: `404 form_not_found` (not one of the provided forms), `400 invalid_webhook_url`, `422 output_refused` (the message text was refused), `502 sms_send_failed` or `email_send_failed`.

## Step 2: Watch the form during the call

In a voice agent, `ctx.watchFormSession(token)` follows the form while the call is live. It returns a function that stops watching. It is not available on a text conversation.

```ts
import { defineAgent, defineTool } from '@voicelayer/sdk';

export default defineAgent({
  name: 'intake',
  prompt: 'You collect intake details. When the caller has the form open, read their answers back.',
  capabilities: ['system.say'],
  tools: {
    ...defineTool({
      name: 'watch_form',
      description: 'Start following the form the caller was sent',
      input: { token: 'string' },
      run: async ({ token }, ctx) => {
        // keep the returned function if you want to stop watching early
        ctx.watchFormSession(token);
        return { watching: true };
      }
    })
  }
});
```

While you watch, the call's timeline records the form's events, with `source: 'form'`: `form.opened`, `form.field_set`, `form.fields_set`, `form.status`, `form.call_state` and `form.submitted`.

## Step 3: Read what was submitted

`GET /v1/forms/responses` lists submissions. Filter with `formId`, `limit` (1 to 200) and `before` (a time). This route takes a signed-in dashboard session, not an API key.

If you set `webhookUrl` when you created the link, VoiceLayer also posts to that address when the form is submitted.

## Next steps

- [Voice agents in code](https://docs.vlayers.ai/developers/sdks/voice-agents).
- [Receive with webhooks](https://docs.vlayers.ai/developers/receive/webhooks).
