# Holder

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

> A Holder is the Party that holds a Share or an Instrument on a Company’s cap table.

A Holder is the [Party](/business/nouns/party) that holds a [Share](/business/nouns/share) or an [Instrument](/business/nouns/instrument) on a [Company](/business/nouns/company)’s cap table.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `party` | [Party](/business/nouns/party) | Yes | The person or entity behind the holding. |

## Object
```json
{
  "$id": "https://api.sb/quietcopy.com/holders/holder_1",
  "$type": "Holder",
  "party": "party_1"
}
```

## Relationships
- <a id="rel-instruments"></a>A Holder **has** many [Instruments](/business/nouns/instrument): each [Instrument](/business/nouns/instrument) belongs to one Holder, who sees it, its vesting and its documents. `instruments`, inverse [`heldBy`](/business/nouns/instrument#rel-held-by).
- <a id="rel-shares"></a>A Holder **has** many [Shares](/business/nouns/share): each [Share](/business/nouns/share) record belongs to one Holder; a transfer writes a new record for the new Holder. `shares`, inverse [`heldBy`](/business/nouns/share#rel-held-by).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| <a id="create"></a>[Holder.create](/business/nouns/holder/create) | Creates a Holder. Inherited from [Noun](/business/nouns/noun). | None. | `Holder.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Holder.get](/business/nouns/holder/get) | Returns one Holder by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Holder.list](/business/nouns/holder/list) | Returns Holders, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Holder.update](/business/nouns/holder/update) | Changes the given properties of a Holder. Inherited from [Noun](/business/nouns/noun). | None. | `Holder.updated` | Two-way: `try`, `send`, `do` |

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

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

## Call it

**Ask**

```text
Add a holder to TutorLoop with a party.
```

**API**

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

```json
{
  "api": "https://api.sb/tutorloop.com",
  "holder": {
    "$id": "https://api.sb/tutorloop.com/holders/holder_1",
    "$type": "Holder",
    "party": "party_1"
  },
  "action": {
    "$id": "https://api.sb/tutorloop.com/actions/action_1",
    "operation": "Holder.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/tutorloop.com/actions/action_1"
  }
}
```

**SDK**

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

const holder = await $.Holder.create({ party: 'party_1' })
```

**CLI**

```bash
npx startup-builder do Holder.create --json '{"party":"party_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Holder.create({ party: 'party_1' })"
  }
}
```

## Example
A founder holds 4 million common [Shares](/business/nouns/share) and an option [Instrument](/business/nouns/instrument) in her [Company](/business/nouns/company). The cap table shows one Holder for her, with both holdings under it.