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, a poll. 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.