Form links
Send a person a link to a form during a call, watch them fill it in, and read what they submit.
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:writescope. See Authentication and API keys. - 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.
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": "[email protected]", "subject": "Your intake form" }
}'formIdandrecipientPhone(E.164) are required.recipientName,prefill,webhookUrl,callbackFromNumber,sendSmsandsendEmailare optional.ttlSecondsis 60 seconds to 90 days. After that the link isexpired.- Set
sendSms(phoneNumberId, optionalbodyPrefix) orsendEmail(to, optionalsubjectandbodyPrefix), or both. Set neither to get the link back and deliver it yourself.
{
"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.
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.