Building Projects
A project in VocaLoop is the thing you send to people: its fields, layout, branding, link-expiry rules, and webhook all hang off it. This page covers creating a project, generating its UI with the AI builder, and every setting on the project detail page.
The default project
Every account starts with an active project named default, created at signup. It is the fallback target whenever an API request doesn't name a project (external sends, submissions, generate-send without a namespace), and it cannot be deleted.
Creating a project
On the dashboard (Projects in the sidebar), click Add Project.
Give it a name (max 200 characters) and an optional description (max 1000 characters).
The project is created with status Inactive — it can't receive fill requests until you save a preview and activate it.
Deleting a project deletes everything under it: its preview, templates, submissions, and API keys. The default project is the one exception — it can't be deleted.
The AI project builder
Open a project and describe what you want in the instructions box — for example "a job application project: full name, email, phone, position (dropdown: Engineer / Designer / PM), resume upload, and a cover-letter text area".
Generate — produces the project UI and renders a live, fillable preview.
Save — persists the preview. Only a saved preview counts; generating alone changes nothing.
Generation requires OPENAI_API_KEY in the root .env (see Getting Started).
Under the hood the builder writes OpenUI-lang, a small Python-like DSL that compiles to the project's UI spec. You can regenerate at any time; the new preview replaces the old one when saved. Requests that were already sent keep a snapshot of the UI they were sent with, so editing a project never breaks links that are already in someone's inbox.
Supported field types
| Type | Renders as | Notes |
|---|---|---|
text | Single-line input | |
textarea | Multi-line input | |
number | Numeric input | |
email | Email input | Validated format |
phone | Phone input | |
date | Date picker | |
select | Dropdown | Needs a list of options |
radio | Radio group | Needs a list of options |
checkbox | Checkbox | |
file | File upload | Per-field size cap (max_size_mb); uploads go to S3, 10 MB hard limit |
Every field has a label, a name (the key it gets in submission data), and optional placeholder, required flag, and default value. Layout elements — headings, text blocks, cards, stacks, dividers, and images — let the builder arrange fields into sections.
Testing a preview
The rendered preview is fillable. Submitting it records a real submission row with channel preview, so you can verify the data shape (and your webhook) before sending anything to real people. Preview submissions appear on the Responses page alongside the rest.
Project settings
On the project detail page:
| Setting | Default | What it does |
|---|---|---|
| Status | Inactive | Only Active projects accept fill requests and public fills. Activation requires a saved preview |
| Link expiry | Empty (links never expire) | How long a sent fill link stays usable. Empty = links never expire. A resend restarts the window |
| Webhook URL | — | An http(s) URL that receives a POST for every submission. See Webhooks |
Project branding
Branding cascades: project setting → account setting (Branding page) → built-in defaults. Anything you set on the project overrides your account default for that project only.
Logo and cover image — uploaded to S3 (S3 credentials required in
.env); shown on the public fill page.Colors — primary (buttons/accents), project background, and page background, as hex values.
Custom CSS — free-project CSS (up to 20,000 characters) injected into the fill page for full control.
The fill page
Every project has a public fill page at /fill/<id> — no login required; the unguessable UUID in the link is the credential. There are two kinds of links:
Request links (
/fill/<request_id>) — created when you send the project to someone; single-use and subject to the expiry window.The project's direct link (
/fill/<project_id>) — shareable anywhere; anyone with it can submit while the project is active.
How links are sent, tracked, and expired is covered in Sending & Tracking.