703 - Your first form

• 701An automation that answers a requestWhat an endpoint is, the request a handler is handed and the answer it returns, who binds it, the limits a request runs under, and what a caller is told.
• 702A lookup a partner system callsThe three access modes, API keys and per-caller limits, one audit row per request, refusals by reason, signed tokens, and the Endpoints page.
• 703Your first formA form the agent writes: fields, live choices, field-by-field refusals, the checks the platform runs first, the hosted page, and submissions as a table.
• 704Putting the form on your site, or in a reportEmbedding in an asset and on an allowed site, named bot checks, the honeypot, and the minimum fill time.
• 705Sensitive fieldsEncryption before storage, who reads in clear and where, audited reads, exports, and why a file field cannot be sensitive.
• 706From submission to actionAn automation that runs once per submission, validation against live data, bursts and failures, and writes to other systems.
• 707Capstone: the supplier form end to endThe demo tenant’s supplier program assembled: form, page, table, intake automation, and a report joining applications to the warehouse.

form_spec(req)

Called when someone opens the form. Returns the fields in order, any starting values, the confirmation shown on success, and the minimum time a person takes to fill it in.

form_submit(req, values)

Called with a submission the platform has already checked against the spec. Returns nothing to accept, errors keyed by field to refuse, or its own confirmation.

the binding

An administrator binds the automation to an endpoint that answers GET for the form and POST for a submission, as in 701.

company_name

text, required

Up to 200 characters.

contact_name

text, required

Up to 120 characters.

contact_email

email, required

Must be an email address.

contact_phone

text

Optional, up to 40 characters.

category

single choice, required

The 50 product categories, read from the warehouse when the form opens.

pilot_store

single choice, required

All 303 active stores, read from the warehouse when the form opens, labeled with city and state.

annual_volume_usd

number, required

Between 1,000 and 50,000,000.

first_delivery

date, required

A calendar date.

tax_id

text, required, sensitive

Up to 10 characters, encrypted before it is stored. Lesson 705.

insurance_certificate

file, required

One PDF or image, up to 5 MB, judged by its bytes rather than its name.

notes

long text

Optional, up to 2,000 characters.

agree_terms

checkbox, required

The supplier code of conduct.

def form_spec(req):
    """The supplier-onboarding form, with its category and pilot-store choices read from the warehouse."""
    categories = platform.query(
        "SELECT CAST(category_id AS varchar) AS value, category_name AS label " +
        "FROM warehouse.public.categories ORDER BY category_name",
        connection = "acme",
    )
    stores = platform.query(
        "SELECT CAST(store_id AS varchar) AS value, " +
        "store_name || ' (' || city || ', ' || state || ')' AS label " +
        "FROM warehouse.public.stores WHERE is_active ORDER BY state, city, store_id",
        connection = "acme",
    )
    return {
        "fields": [
            ...
            {"name": "category", "type": "single_choice", "label": "Primary product category",
             "required": True, "choices": categories["rows"]},
            {"name": "pilot_store", "type": "single_choice", "label": "Pilot store",
             "help": "The store you would deliver to first.", "required": True,
             "choices": stores["rows"]},
            ...
        ],
        "confirmation": "Thank you. The ACME vendor team reviews every application within five business days.",
        "min_fill_seconds": 5,
    }

def form_submit(req, values):
    """Checks the tax ID's shape and the code of conduct before accepting."""
    errors = {}
    if not valid_ein(values["tax_id"]):
        errors["tax_id"] = "Enter the EIN as NN-NNNNNNN."
    if not values["agree_terms"]:
        errors["agree_terms"] = "The code of conduct must be accepted."
    if errors:
        return {"errors": errors}
    return None

1. 1

   A signed form token

   The spec is signed into a token when the form opens, bound to this endpoint and good for a day. A submission without it, with an altered one, or with one from another form is refused 400. The platform keeps no copy; the submission brings its spec back.

2. 2

   A hidden honeypot field

   The page renders a field named website that people never see. Only a program filling every field it finds fills it, and that submission is refused 400.

3. 3

   A minimum fill time

   A submission sooner than the spec’s minimum after the form opened is refused 400. The supplier form sets five seconds.

4. 4

   Every field against the spec

   An undeclared field, a required field left empty, a value of the wrong type, a choice that is not offered, a value past its limit, or a changed hidden field is refused 422 with each field’s error.

5. 5

   Then the automation

   Only a submission that passed all of that reaches form_submit, with numbers as numbers, checkboxes as true or false, and files described by name, type, size, and address.

→ manage_script
  {
    "command": "endpoint_set",
    "name": "acme-supplier-onboarding",
    "endpoint": "supplier-onboarding",
    "methods": ["GET", "POST"],
    "auth_mode": "bot_check",
    "bot_check": "acme-public-forms",
    "checked_methods": ["POST"],
    "max_body_bytes": 10485760,
    "connection": "scratch"
  }

← {
    "endpoint": "supplier-onboarding",
    "form": {
      "source": "form-supplier-onboarding",
      "table": "webhook_form_supplier_onboarding",
      "connection": "scratch",
      "created": true
    },
    "message": "... Each accepted submission is stored as a row of
                webhook_form_supplier_onboarding on connection scratch."
  }

→ trino_query
  SELECT event_type,
         json_extract_scalar(payload, '$.values.company_name') AS company,
         json_extract_scalar(payload, '$.values.tax_id')       AS tax_id_stored,
         json_extract(payload, '$.sensitive')                  AS sensitive
  FROM scratch.uploads.webhook_form_supplier_onboarding
  ORDER BY received_at DESC LIMIT 3

← event_type       company                     tax_id_stored        sensitive
  form_submission  Brightleaf Tea Company      encb:iuDbLfC7zeD/…   ["tax_id"]
  form_submission  Summit Trail Outfitters     encb:/m1DoqxCCX/…    ["tax_id"]
  form_submission  Tidewater Seafood Partners  encb:D8uxIvpp5NFZ…   ["tax_id"]

No visual builder

The agent writes the form from what you ask for.

One page, no conditions

Every field is shown. There is no conditional logic and no multi-page flow.

No payments

A form collects information, not money.

No respondent receipts

The person sees the confirmation on the page. An automation that runs per submission (706) can post or deliver to your own channels.

About 10 MB per submission

Files and fields together, across every file field.