Create a hosted form and get back a public URL to share.
Call this when someone wants to collect answers from other people — a signup, an
intake questionnaire, an RSVP, a feedback survey. For changing a form that already
exists call update_form instead; to see what forms exist call list_forms.
You write the fields. Infer the type from what the question is actually asking: an
email address is type "email", not "short_text"; a 1-5 rating is "rating"; a yes/no
is "boolean". Write "key" values that read well as spreadsheet column headers,
because that is where they end up.
Example:
{
"title": "Workshop signup",
"fields": [
{ "key": "full_name", "type": "short_text", "label": "Your name", "required": true },
{ "key": "email", "type": "email", "label": "Email address", "required": true },
{ "key": "session", "type": "single_select", "label": "Which session?",
"options": [{ "value": "am", "label": "Morning" }, { "value": "pm", "label": "Afternoon" }] },
{ "key": "dietary", "type": "long_text", "label": "Dietary requirements",
"visible_when": { "field": "session", "op": "eq", "value": "pm" } }
]
}
A "visible_when" condition may only reference a field defined earlier in the array.
Every question is required unless you say otherwise — "required" defaults to true,
so omit it for a question someone must answer and set it to false deliberately for
one they may skip. A "rating" is the one exception: it defaults to optional, because
ratings arrive as a battery and requiring each row makes someone with no opinion
invent a middle score. Set "required": true on a rating if you really need it.
**Length is a design decision, and it is yours.** Every question costs responses.
Someone asking for "a list of activities" or "some questions about X" has not told
you how many they want — they have left it to you, and the honest answer is usually
fewer than you can think of. Aim for eight or ten questions. Past that, ask before
you build: "I can rate twelve activities or pick the six most likely — which?"
**Use what you know about the occasion to narrow, not to enumerate.** A Nashville
girls trip suggests honky-tonks, hot chicken and a pedal tavern; a company offsite
suggests none of those. That knowledge is what makes a form feel written rather than
generated — but it earns its place by producing the six best options, not every
option you can name. A respondent scoring fourteen activities stops reading and
starts pattern-filling, and the owner gets noise back.
**Say what you assumed.** If you inferred a year, a city, a start date or an
audience from context, name it in one line when you hand over the link, so it can be
corrected before the form goes out.
Before creating the form, ask about any question you are not sure of rather than
guessing. A required question a respondent cannot answer is a dead end: they abandon
the form, and the owner never learns why. Three cases worth a follow-up almost every
time:
- a question that will not apply to everyone ("spouse's name", "company"), which is
either optional or belongs behind a "visible_when" condition;
- anything sensitive — a phone number, an address, a date of birth — where making it
required costs responses;
- a battery of similar questions — several ratings in a row — which should be
optional, so someone with no opinion can skip rather than invent a middle score.
A "rating" is optional unless you say otherwise, for exactly this reason.
One short question covering all of them is better than one per field. If the person
has already been clear, or has asked you to just build it, build it.
Three settings exist for when someone asks for them, all on the paid plan:
"settings.theme" sets the form's colours, "settings.password" hides the form behind a
shared password (for "only my team should see this"), and "settings.payment_links"
puts payment buttons on the thank-you page (for "people should Venmo me $25 when they
sign up"). Say how much to pay in
"thanks_message"; the buttons only link to the owner's page and formset never learns
whether anyone paid.
