# Acquisition

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

> An Acquisition is how a Visitor or Prospect first arrived, recorded on its first Event: the referrer kind, the Play, the campaign, and the medium.

An Acquisition is how a [Visitor](/business/nouns/visitor) or [Prospect](/business/nouns/prospect) first arrived, recorded on its first [Event](/business/nouns/event): the referrer kind, the [Play](/business/nouns/play), the campaign, and the medium.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `string` | Yes | The referrer kind: one of `search`, `answer`, `agent`, `referral`, `ad`, `outbound`, or `direct`. |
| `play` | [Play](/business/nouns/play) | No | The Play that produced the first touch, when one did. |
| `venue` | `string` | No | The venue id where the touch happened, such as a search engine, an answer engine, or a Mailbox. |
| `campaign` | [Campaign](/business/nouns/campaign) | No | The Campaign behind a paid placement or a scheduled send. |
| `ad` | [Ad](/business/nouns/ad) | No | The Ad clicked, for a paid or house placement. |
| `page` | [Page](/business/nouns/page) | No | The first Page the Visitor saw. |
| `keyword` | [Keyword](/business/nouns/keyword) | No | The Keyword or prompt, when the venue reports it. |
| `angle` | `string` | No | The angle the first touch carried: the message the Play ran. |
| `referrer` | `string` | No | The linking host, as the request reported it. |
| `partner` | [Partner](/business/nouns/partner) | No | The Partner or creator credited, for referral, creator and commission Plays. |
| `reported` | `text` | No | What the person answered when asked how they heard, kept word for word. |
| `at` | `datetime` | Yes | When the first Event arrived. |

## Object
```json
{
  "$id": "https://api.sb/routewise.dev/acquisitions/acquisition_1",
  "$type": "Acquisition",
  "kind": "search",
  "play": "play_1",
  "venue": "google-search",
  "campaign": "campaign_1",
  "ad": "ad_1",
  "page": "page_1",
  "keyword": "keyword_1",
  "angle": "Example angle",
  "referrer": "news.ycombinator.com",
  "partner": "partner_1",
  "reported": "Example reported",
  "at": "2026-10-22T12:00:00Z"
}
```

## Relationships
- <a id="rel-customers"></a>An Acquisition **has** many [Customers](/business/nouns/customer): a [Customer](/business/nouns/customer) inherits the Acquisition of the [Lead](/business/nouns/lead) it was; [Metrics](/business/nouns/metric) and payouts read this one row. `customers`, inverse [`acquiredBy`](/business/nouns/customer#rel-acquired-by).
- <a id="rel-leads"></a>An Acquisition **has** many [Leads](/business/nouns/lead): each [Lead](/business/nouns/lead) keeps the Acquisition that first brought it, through either door: a [Visit](/business/nouns/visit) or an outbound reply. `leads`, inverse [`acquiredBy`](/business/nouns/lead#rel-acquired-by).
- <a id="rel-prospects"></a>An Acquisition **has** many [Prospects](/business/nouns/prospect): a [Prospect](/business/nouns/prospect)’s Acquisition names the outbound [Play](/business/nouns/play) and [Mailbox](/business/nouns/mailbox) that first reached it. `prospects`, inverse [`acquiredBy`](/business/nouns/prospect#rel-acquired-by).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| <a id="get"></a>[Acquisition.get](/business/nouns/acquisition/get) | Returns one Acquisition by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Acquisition.list](/business/nouns/acquisition/list) | Returns Acquisitions, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |

An Acquisition is kept forever and never edited: it has no `update` or `delete`.

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

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Acquisition.get` | Yes | Yes | Yes | Yes |
| `Acquisition.list` | Yes | Yes | Yes | Yes |

## Call it

**Ask**

```text
Show me the latest acquisition.
```

**API**

```bash
curl https://api.sb/ledgerlark.com/acquisitions/acquisition_1 \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/ledgerlark.com",
  "$type": "Acquisition",
  "$id": "https://api.sb/ledgerlark.com/acquisitions/acquisition_1",
  "acquisition": {
    "$id": "https://api.sb/ledgerlark.com/acquisitions/acquisition_1",
    "$type": "Acquisition",
    "kind": "search",
    "at": "2026-10-22T12:00:00Z"
  },
  "links": {
    "self": "https://api.sb/ledgerlark.com/acquisitions/acquisition_1",
    "up": "https://api.sb/ledgerlark.com/acquisitions"
  }
}
```

**SDK**

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

const acquisition = await $.Acquisition.get({ id: 'acquisition_1' })
```

**CLI**

```bash
npx startup-builder do Acquisition.get --json '{"id":"acquisition_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Acquisition.get({ id: 'acquisition_1' })"
  }
}
```

## Example
A clinic manager asks [ChatGPT](/workflows/plays#chatgpt) for shift-scheduling software and opens the pricing [Page](/business/nouns/page) it cites. Her first Event writes an Acquisition with `kind: answer`, `venue: chatgpt` and the [answer engine optimization](/workflows/plays/aeo) Play. When she subscribes, her [Customer](/business/nouns/customer) record keeps it, and that Play’s ledger counts her revenue.