# Purpose

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

> A Purpose is a named reason personal data is processed, with a lawful basis per jurisdiction.

A Purpose is a named reason personal data is processed, with a lawful basis per jurisdiction.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | Yes | The reason, such as marketing email or call recording. |

## Object
```json
{
  "$id": "https://api.sb/kilnbakery.com/purposes/purpose_1",
  "$type": "Purpose",
  "name": "Kiln Bakery"
}
```

## Relationships
- <a id="rel-consents"></a>A Purpose **has** many [Consents](/business/nouns/consent): the Purpose the [Consent](/business/nouns/consent) permits processing for, and nothing beyond it. `consents`, inverse [`covers`](/business/nouns/consent#rel-covers).

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

## Call it

**Ask**

```text
Add a purpose to PetPantry.
```

**API**

```bash
curl -X POST https://api.sb/petpantry.shop/purposes \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"PetPantry"}'
```

```json
{
  "api": "https://api.sb/petpantry.shop",
  "purpose": {
    "$id": "https://api.sb/petpantry.shop/purposes/purpose_1",
    "$type": "Purpose",
    "name": "PetPantry"
  },
  "action": {
    "$id": "https://api.sb/petpantry.shop/actions/action_1",
    "operation": "Purpose.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/petpantry.shop/actions/action_1"
  }
}
```

**SDK**

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

const purpose = await $.Purpose.create({ name: 'PetPantry' })
```

**CLI**

```bash
npx startup-builder do Purpose.create --json '{"name":"PetPantry"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Purpose.create({ name: 'PetPantry' })"
  }
}
```

## Example
"Send product updates" is a Purpose with consent as its lawful basis. "[Bill](/business/nouns/bill) the [Customer](/business/nouns/customer)" is a Purpose with contract as its basis.