Prefilled form sessions
Use your published embedded form configuration to create a one-time link. Your server supplies optional prefill data; your customer opens the link, reviews and edits the fields, gives consent, and submits. Results arrive on the same webhooks and session API as the embedded iframe.
Create a session
POST /v1/forms/:formId/sessions with your API key. formId is the embedded form id from the dashboard (ecfg_…). The form must be published.
POST https://test-api.veroid.com.au/v1/forms/ecfg_…/sessions
X-API-Key: sk_test_…
Content-Type: application/json
{
"consentVersion": "1.1",
"reference": "your-customer-ref",
"prefill": {
"givenName": "Jane",
"familyName": "Citizen",
"dateOfBirth": "1990-01-15",
"licenceNumber": "12345678",
"stateOfIssue": "NSW"
}
}Optional biometrics (boolean, default false) adds a guided ID photo and live selfie on the form link, with face match and liveness scored on the server the same way as hosted verify sessions. Face match and liveness are included in the session result at no extra credit cost. When biometrics is true, consentVersion must be 2.1-biometric or omitted (it defaults to 2.1-biometric). Document-only sessions default to 1.1. See Consent for Information Match Agent and biometric wording on the page.
On the form link, failed document quality checks prompt one guided retake with a clear tip, then the customer can continue. Quality concerns are stored on the session result. A refreshed page uses captureProgress from GET /v1/form-link/sessions/:token to resume the correct licence side. Document JPEGs are downloadable for 24 hours after capture (same retention as hosted verify sessions).
Response (201)
{
"success": true,
"sessionId": "vs_…",
"sessionUrl": "https://…/f/…",
"expiresAt": "2026-11-11T15:00:00.000Z",
"reference": "your-customer-ref",
"status": "created",
"consentVersion": "1.1"
}Send the customer sessionUrl. Links expire 4 hours after creation (expiresAt). No SMS is sent. The public page shows the Information Match Agent consent wording for your business name when configured, and your published form logo when logo upload is enabled.
Optional Idempotency-Key header: scoped to this create endpoint per account and environment. Replays return the same response with Idempotent-Replayed: true. See Idempotency.
Expiry
After expiresAt, the link no longer opens the form. The page shows This link has expired and the session API reports status: "expired". VeroID applies that status on a schedule within a few minutes, when someone opens the expired link, or on GET /v1/verify/sessions/:sessionId. The first transition sends verify_session.expired once. Prefill data is purged on the retention schedule.
Document scan autofill (biometrics)
When the form link includes biometrics and the customer's ID photos are accepted, empty fields on the details step may be filled from a free document read (same field mapping as document extract, no verification credits). The page labels those fields so the customer can review and edit them. Values you supplied in prefill are never overwritten. Scan-filled fields stay editable even when allowEditingPrefilledFields is false; only API prefill follows that lock.
Prefill rules
- Any field the embedded form can collect for the form's document type(s) may appear in
prefill, including Medicare name lines, BDM participant names, registration fields, and document numbers. - Unknown or invalid
prefillkeys return HTTP400with codeINVALID_PREFILLand a field-specificmessage. - Each key must be valid for the form's fixed or allowed document types.
- Prefilled values appear on the public form (unlike embed iframe prefill, which hides fields). By default they are read-only when your embedded form configuration has
allowEditingPrefilledFieldsoff (the default). Enable editing in the dashboard embedded form builder if customers may correct values before submit. - Empty or omitted prefill values leave the matching form field editable. Locked fields return in
lockedPrefillFieldKeysonGET /v1/form-link/sessions/:token.
{
"error": "Bad Request",
"code": "INVALID_PREFILL",
"message": "Unknown prefill field: notARealField"
}Cancel
POST /v1/forms/sessions/:sessionId/cancel ends an open session early. You can also use POST /v1/verify/sessions/:id/cancel.
{
"success": true,
"id": "vs_…",
"status": "cancelled",
"expiresAt": "2026-11-11T15:00:00.000Z",
"consentVersion": "1.1",
"channel": "form_link",
"createdAt": "2026-11-11T11:00:00.000Z",
"completedAt": "2026-11-11T12:00:00.000Z"
}Unknown session id returns 404 with message: "Session not found". Cancelling a session that is already completed, failed, expired, cancelled, or sms_failed returns 409 with message: "Session already terminal". Cancel sends verify_session.cancelled; expiry without cancel sends verify_session.expired.
Results
Poll GET /v1/verify/sessions/:sessionId or listen for verify_session.completed / verify_session.failed webhooks. Billing matches the embedded document form. When biometrics was true, results include livenessScore and faceMatchScore like hosted sessions; document-only sessions return null for those fields.
On the test API you can also use MCP tools create_form_session and cancel_form_session (see MCP Server).