Developer Docs

Public Forms

Collect structured responses from anyone – no app, no login. Every submission becomes a real entry in the target list. This page covers the form page's developer features: field types, submission formats, URL prefill, redirect and consent options.

Overview

A public form is created in the Alistia app from a list's real field definitions. It is served at https://alistia.app/f/?token={token} and backed by the forms.alistia.app API.

Forms are opt-in and revocable: the owner picks the fields, and can disable or delete the form at any time. Submissions are validated against the form's field configuration — unknown fields are rejected.

Endpoints

GET https://forms.alistia.app/v1/forms/{token}

Returns the public render config: title, description, fields (with placeholder, helpText, options), successMessage, redirectUrl and privacyUrl.

POST https://forms.alistia.app/v1/forms/{token}/submit

Creates one entry from the submitted values. Body:

{
  "values": { "{fieldId}": … },
  "_hp": "",          // honeypot – must stay empty
  "_elapsedMs": 5400  // time the visitor spent filling the form
}

Returns 201 with entryId and successMessage, or an error code: missing_required_field, invalid_field, disabled, expired, closed.

Field types & submitted formats

Forms support these Alistia field types. The web form renders a matching input and submits values in the app's storage format:

Type	Input	Submitted value
`text`, `longText`	text / textarea	string
`number`	number input	number
`boolean`	switch	`true` / `false`
`date`, `time`, `datetime`	native pickers	ISO-like strings (`YYYY-MM-DD`, `HH:MM`)
`select`, `status`	dropdown	option string
`multiSelect`	checkbox group	array of option strings
`tags`	comma-separated input	array of strings
`rating`	tappable stars	number 1–5
`color`	native color picker	`#RRGGBB`
`email`, `phone`, `ean`	typed inputs	string
`link`, `imageUrl`, `videoUrl`	URL input	string

Cloud media, files, signatures and internal reference fields are never available in public forms.

Form options

Option	Effect
Closing date	After this date the form returns `410 expired` and stops rendering.
Submission limit	Once reached, submissions return `403 closed` — e.g. 40 seats.
Notifications	The owner (and list members) get a push notification per submission — can be turned off.
Thank-you text	Shown on the confirmation page after submitting.
Redirect URL	After a successful submission the page briefly shows the confirmation, then redirects here.
Privacy policy URL	If set, the form requires a consent checkbox (with a link to that policy) before submitting.

Prefill via URL parameters

Any field can be pre-populated through the form link — perfect for per-audience invitations or QR codes.

Append parameters using either the field label (matched case-insensitively) or the field id:

# label-based (readable)
https://alistia.app/f/?token=TOKEN&Anlass=Sommerfest&Personen=2

# fieldId-based (stable across renames)
https://alistia.app/f/?token=TOKEN&69be89f9…=Sommerfest

Format per type: plain strings for text-like fields; the exact option string for select/status; comma-separated options for multiSelect (&Themen=A,B); a number 1–5 for rating; 1/true/ja for boolean; #RRGGBB for color. Values must be URL-encoded. Visitors can still change prefilled values before submitting.

Spam protection

Honeypot: the hidden _hp field must stay empty — bots that fill it are silently dropped.
Timing: submissions faster than a minimum fill time (_elapsedMs) are silently dropped.
No CAPTCHAs, no cookies, no tracking.

Building your own client? POST directly to the submit endpoint with the body shown above. Include a realistic _elapsedMs and keep _hp empty. CORS is open (Access-Control-Allow-Origin: *).