Sign-up forms

A form collects sign-ups on a page Hermeticor hosts, or on your own site. Each submission creates or updates a contact, adds them to your lists and tags, and records consent only for the boxes they ticked.

What you need first

• A list to collect people into (POST /v1/lists {"name":"Webinar: Bring your own provider (Nov 2026)"}).

• A key with forms:write.

1. Create the form

curl -s -X POST "$BASE/v1/forms" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Webinar registration","kind":"full_page","definition":{
    "steps":[{"title":"Save your seat","fields":[
      {"type":"email","key":"email","label":"Work email","required":true},
      {"type":"text","key":"first_name","label":"First name","required":true,"saveTo":"firstName"},
      {"type":"company","key":"company","label":"Company"},
      {"type":"phone","key":"phone","label":"Mobile (optional)"},
      {"type":"consent_email","key":"consent_email","label":"Email me the recording and product news",
       "disclosureText":"I agree to receive emails from Example Co. Unsubscribe at any time.",
       "disclosureVersion":"2026-11-webinar","privacyUrl":"https://example.com/privacy"},
      {"type":"consent_sms","key":"consent_sms","label":"Text me a reminder",
       "disclosureText":"I agree to receive one SMS reminder. Reply STOP to opt out.","disclosureVersion":"2026-11-webinar-sms"}]}],
    "success":{"type":"message","title":"You are registered","text":"See you on 19 November."},
    "listIds":["<listId>"],"tags":["webinar-2026-11"],"submitLabel":"Register",
    "minFillMs":1500,"maxPerIpPerDay":20}}'

• Consent fields need disclosureText and disclosureVersion. Hermeticor stores both with the consent, so you can show later exactly what the person agreed to.

• A consent box is never ticked for the person. Consent is recorded only when they tick it.

• saveTo writes the answer to a contact field.

• minFillMs and maxPerIpPerDay stop bots: a submission faster than 1.5 seconds is dropped quietly.

2. Publish it

curl -s -X POST "$BASE/v1/forms/<formId>/publish" -H "Authorization: Bearer $HERMETICA_API_KEY"

The hosted form is at $BASE/p/f/<workspaceId>.<formId>. Your workspace id is in GET /v1/workspace.

3. Submit from your own site

The public submit needs no key:

curl -s -X POST "$BASE/p/f/<workspaceId>.<formId>/submit" \
  -H "Content-Type: application/json" \
  -d '{"data":{"email":"maya@example.com","first_name":"Maya","consent_email":true},"startedAt":1762185600000}'

startedAt is when the form was shown, in milliseconds since 1970. Missing required fields come back as field errors.

4. Read the sign-ups

curl -s "$BASE/v1/forms/<formId>/submissions" -H "Authorization: Bearer $HERMETICA_API_KEY"
curl -s "$BASE/v1/forms/<formId>/submissions/export.csv" -H "Authorization: Bearer $HERMETICA_API_KEY"

5. A pre-filled link for someone you know

curl -s -X POST "$BASE/v1/forms/<formId>/prefill-link" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"profileId":"<profileId>"}'

Put the link in an email so the person only has to confirm.

Next: Landing pages.