> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pinnacle.sh/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server.

## Hosted Forms

Collect structured responses from your recipients with Pinnacle-hosted forms. Mint a form URL, deliver it over SMS or RCS in the same call, and receive completed submissions as a new `FORM.SUBMISSION` webhook event.

Browse, build, and theme forms in the [Pinnacle Dashboard → Forms](https://app.pinnacle.sh/dashboard/forms).

### What's new?

**Form endpoints**

* [`POST /forms`](/api-reference/forms/create-form) — create a form without sending it (returns the public `https://forms.pinnacle.sh/{form_id}` URL).
* [`POST /forms/send`](/api-reference/forms/send-form) — create (or reuse) a form and deliver its URL over SMS or RCS in one call. When `to` is provided, Pinnacle dispatches the message and the recipient is recorded on the response (`submission.to` plus the outbound `message_id`). Omit `to` to mint a standalone submission URL for embedding in your own outreach.
* [`GET /forms/{id}`](/api-reference/forms/get-form), [`PATCH /forms/{id}`](/api-reference/forms/update-form) — retrieve and partial-update a form.
* [`POST /forms/list`](/api-reference/forms/list-forms), [`POST /forms/{id}/submissions/list`](/api-reference/forms/list-form-submissions) — paginated listings of forms and of their completed submissions.

**16 field types out of the box**

Text, textarea, email, url, phone (auto-formats + E.164-normalized on submit), number, range slider, rating stars, date, time, datetime, color picker, select, radio group, checkbox group, and an `address` input with built-in Google Places autocomplete.

**Theme overrides**

Per-form `theme_override` layered on top of your team's default theme — tweak colors, background (solid / gradient / pattern / image), font family, corner radius, submit button label, success message, and post-submission redirect URL. Configure team-wide defaults from the [Pinnacle Dashboard → Forms](https://app.pinnacle.sh/dashboard/forms).

**Updatable submissions**

Set `can_update: true` to let a recipient reopen their submission URL and edit their answers. The form rehydrates with their prior values; `submission_count` reflects distinct recipients and `last_submitted_at` tracks the latest edit.

### New webhook event: `FORM.SUBMISSION`

When a recipient completes a form, every webhook subscribed to the sender receives a `FORM.SUBMISSION` event. The payload carries the sender, an optional conversation reference, the form summary, and a resolved snapshot of every field paired with the submitted value — ready to render or route on without a separate `get_form` call. Manage subscribers from the [Pinnacle Dashboard → Webhooks](https://app.pinnacle.sh/dashboard/development/webhooks).

```json
{
  "type": "FORM.SUBMISSION",
  "sender": "agent_iM9wQcyBBjYn",
  "conversation": { "id": "convo_…", "from": "agent_…", "to": "+14155551234" },
  "form": { "id": "form_…", "url": "https://forms.pinnacle.sh/form_…", "name": "Contact request" },
  "submission": {
    "id": "fsub_…",
    "from": "agent_iM9wQcyBBjYn",
    "to": "+14155551234",
    "data": { "full_name": "Ada Lovelace", "email": "ada@example.com" },
    "fields": [
      { "key": "full_name", "label": "Full name", "type": "text", "value": "Ada Lovelace" },
      { "key": "email", "label": "Email", "type": "email", "value": "ada@example.com" }
    ],
    "ip_address": "203.0.113.45",
    "user_agent": "Mozilla/5.0 …",
    "submitted_at": "2026-04-24T00:35:04.406Z"
  }
}
```

See the [Receiving Messages and User Events](/guides/messages/receiving) guide for full routing details.