# Form

URL: /business/nouns/form · Id: `noun:form`

> A Form is a set of fields someone fills in on a Site or in a Message, producing a Lead, Evidence, or a Thing.

A Form is a set of fields someone fills in on a [Site](/business/nouns/site) or in a [Message](/business/nouns/message), producing a [Lead](/business/nouns/lead), [Evidence](/business/nouns/evidence), or a [Thing](/business/nouns/thing).

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | `json` | Yes | The fields and their types. |

## Object
```json
{
  "$id": "https://api.sb/quietcopy.com/forms/form_1",
  "$type": "Form",
  "fields": {}
}
```

## Relationships
- <a id="rel-captures"></a>A Form **captures** many [Leads](/business/nouns/lead): each Form submission creates a [Lead](/business/nouns/lead). `captures`, inverse [`capturedBy`](/business/nouns/lead#rel-captured-by).
- <a id="rel-embedded-in"></a>A Form **is embedded in** many [Pages](/business/nouns/page): Forms sit on [Pages](/business/nouns/page); one Form appears on many Pages. `embeddedIn`, inverse [`embeds`](/business/nouns/page#rel-embeds).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| <a id="create"></a>[Form.create](/business/nouns/form/create) | Creates a Form. Inherited from [Noun](/business/nouns/noun). | None. | `Form.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Form.get](/business/nouns/form/get) | Returns one Form by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Form.list](/business/nouns/form/list) | Returns Forms, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Form.update](/business/nouns/form/update) | Changes the given properties of a Form. Inherited from [Noun](/business/nouns/noun). | None. | `Form.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Form.delete](/business/nouns/form/delete) | Deletes a Form; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Form.deleted` | One-way: `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Form.create` | Yes | Yes | Yes | No |
| `Form.get` | Yes | Yes | Yes | Yes |
| `Form.list` | Yes | Yes | Yes | Yes |
| `Form.update` | Yes | Yes | Yes | No |
| `Form.delete` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Add a form to TutorLoop.
```

**API**

```bash
curl -X POST https://api.sb/tutorloop.com/forms \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":{}}'
```

```json
{
  "api": "https://api.sb/tutorloop.com",
  "form": {
    "$id": "https://api.sb/tutorloop.com/forms/form_1",
    "$type": "Form",
    "fields": {}
  },
  "action": {
    "$id": "https://api.sb/tutorloop.com/actions/action_1",
    "operation": "Form.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/tutorloop.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const form = await $.Form.create({ fields: {} })
```

**CLI**

```bash
npx startup-builder do Form.create --json '{"fields":{}}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Form.create({ fields: {} })"
  }
}
```

## Example
The booking Form on a home-inspector directory asks for the address, the closing date, and a phone number. Each submission creates a [Lead](/business/nouns/lead) and offers it to three inspectors.