Take leads from a form

Say what you want to collect: a name, an email, a message, maybe a tick-box for permission to reply.

Your agent declares that form on the project. Each field gets a short identifier, which is what a submission is matched by, and an optional label just for the panel. The wording a visitor reads stays on the page, so you can reword it anytime without touching the form.

Birta has no ready-made form block and doesn't dictate how the form looks. Your agent writes the markup in your site's own design, plus the code that sends a submission.

The «thanks» line and every error line are your site's own wording too: Birta tells the agent which rule a submission broke, and the agent turns that into your voice. Renaming the project or connecting your own domain never breaks the form.

The form starts taking leads once the project has both a declared form and a published site. Declare it before publishing or after, either works, and changing a form later needs no re-publish.

Test it on the published site. A version preview never accepts a submission, on purpose: a lead belongs to the live site, not a draft.

Every accepted submission appears in your project's Forms section with the fields exactly as they arrived, and a later change to the form never rewrites a lead you already have. Your agent can read them too, so ask it to summarize what came in.

You don't need to read this part; it's here so you can see there's no hidden setup. Whenever your agent declares, changes or reads a form, it gets the whole contract back: the rule for every field, where a submission goes, what counts as accepted, every way one can be refused, and how often the form may be sent. The numbers below are the ones this Birta deployment actually enforces.

Form contact ("Talk to us") — 5 fields
1. name ("Name") — short text, required
   JSON string, at most 500 characters. Refused as missing_field, invalid_value, value_too_long.
2. email ("Email") — email, required
   JSON string, matching /^[^\s@]+@[^\s@]+\.[^\s@]+$/, at most 254 characters. Refused as missing_field, invalid_value, value_too_long.
3. topic ("What is it about?") — single choice, optional
   JSON string, one of: demo ("Product demo"), pricing ("Pricing"), support ("Support"). Matched exactly against the declared values, not against what the page displays. Refused as invalid_value, not_an_option.
4. message ("Message") — long text, optional
   JSON string, at most 5000 characters. Refused as invalid_value, value_too_long.
5. consent ("May we reply to you?") — consent, required
   JSON boolean, which has to be true — a required consent counts only as given. Refused as missing_field, invalid_value, consent_not_given.

Submit: POST /_forms/contact on the site's own host — the standard address or a connected domain, whichever the visitor is on. Intake is public: no key, token, project id or absolute address belongs in the markup.
Body: content-type application/json, a JSON object of these field keys and nothing else. An absent key, null, "" and [] all mean not filled in: a required field is refused, an optional one is simply left out of the lead. A submission is at most 65536 bytes. The page's own script sends it — a browser's native form submit posts form-encoded fields and is refused as invalid_body.
Answers: 201 {"status":"accepted"}. A refusal is 400 (invalid_body, unknown_field, missing_field, invalid_value, not_an_option, value_too_long, value_out_of_range, value_too_precise, too_many_values, consent_not_given), 403 (preview_not_accepted), 404 (no_such_form), 413 (payload_too_large), 429 (too_many_submissions, project_busy), carrying {"error","code","field"} — branch on "code", never on the sentence.
Limits: a visitor may send 5 submissions in 10 minutes (too_many_submissions), and the site takes 200 leads in an hour (project_busy). Every attempt spends the visitor's budget, refused ones included: resending a broken submission until it works runs into the limit.
Live only: a version preview refuses every submission as preview_not_accepted — test intake on the published site. A declared form accepts as soon as the project has a published site; declaring or changing a form needs no re-publish.
Keys: the form key and the field keys above are the contract, matched exactly. The text a visitor reads is yours to choose — renaming a label on the page changes nothing here.