# Lead

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

> A Lead is a Contact who raised a hand, by joining a Waitlist, filling a Form, or replying, without accepting an Offer.

A Lead is a [Contact](/business/nouns/contact) who raised a hand, by joining a [Waitlist](/business/nouns/waitlist), filling a [Form](/business/nouns/form), or replying, without accepting an [Offer](/business/nouns/offer). Accepting an Offer, at any [Price](/business/nouns/price), makes a Lead a [Customer](/business/nouns/customer).

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `interest` | `text` | No | What the Lead asked for. |
| `status` | `string` | Yes | One of `new`, `working`, `nurture`, `converted`, or `disqualified`. |
| `owner` | [Worker](/business/nouns/worker) | No | The Worker who answers it. |
| `fit` | `string` | No | One of `strong`, `partial`, or `none`: fit to the ICP as the Lead fit Policy grades it, never set by hand. |

<details>
<summary>Inherited from [Contact](/business/nouns/contact): 3 properties</summary>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `email` | No | The primary email address. |
| `phone` | `string` | No | The primary phone number. |
| `name` | `string` | No | The name the Contact goes by. |

</details>

## Object
```json
{
  "$id": "https://api.sb/quietcopy.com/leads/lead_1",
  "$type": "Lead",
  "email": "mei@quietcopy.com",
  "phone": "Example phone",
  "name": "QuietCopy",
  "interest": "Example interest",
  "status": "new",
  "owner": "worker_1",
  "fit": "strong"
}
```

## Relationships
- <a id="rel-acquired-by"></a>A Lead **is acquired by** one [Acquisition](/business/nouns/acquisition): each Lead keeps the [Acquisition](/business/nouns/acquisition) that first brought it, through either door: a [Visit](/business/nouns/visit) or an outbound reply. `acquiredBy`, inverse [`leads`](/business/nouns/acquisition#rel-leads).
- <a id="rel-captured-by"></a>A Lead **is captured by** one [Form](/business/nouns/form): each [Form](/business/nouns/form) submission creates a Lead. `capturedBy`, inverse [`captures`](/business/nouns/form#rel-captures).
- <a id="rel-converted-from"></a>A Lead **is converted from** one [Prospect](/business/nouns/prospect): a [Prospect](/business/nouns/prospect) becomes a Lead on first engaging, such as a reply or a [Form](/business/nouns/form) submission. `convertedFrom`, inverse [`convertsTo`](/business/nouns/prospect#rel-converts-to).
- <a id="rel-identifies"></a>A Lead **identifies** many [Visitors](/business/nouns/visitor): a Lead, once it gives an address, is tied to every [Visitor](/business/nouns/visitor) id it used, one per device. `identifies`, inverse [`identifiedAs`](/business/nouns/visitor#rel-identified-as).
- <a id="rel-referred-by"></a>A Lead **is referred by** one [Referral](/business/nouns/referral): each [Referral](/business/nouns/referral) sends one Lead to the [Startup](/business/nouns/startup). `referredBy`, inverse [`refers`](/business/nouns/referral#rel-refers).
- <a id="rel-waits-on"></a>A Lead **waits on** one [Waitlist](/business/nouns/waitlist): Leads wait on a [Waitlist](/business/nouns/waitlist) in the order its [Setting](/business/nouns/setting) ranks them. `waitsOn`, inverse [`holds`](/business/nouns/waitlist#rel-holds).

## Lifecycle

| State | Meaning | Moves to |
| --- | --- | --- |
| `new` (first) | It raised a hand, and no Worker works it yet. | `working` by [Lead.assign](/business/nouns/lead/assign); `nurture` by [Lead.nurture](/business/nouns/lead/nurture); `disqualified` by [Lead.disqualify](/business/nouns/lead/disqualify); `converted` on [`Offer.accepted`](/business/events/Offer.accepted) when the Lead buys on its own |
| `working` | Its owner is in touch and owes the next step. | `converted` by [Lead.qualify](/business/nouns/lead/qualify); `converted` by [Lead.convert](/business/nouns/lead/convert); `nurture` by [Lead.nurture](/business/nouns/lead/nurture); `disqualified` by [Lead.disqualify](/business/nouns/lead/disqualify) |
| `nurture` | Not ready to buy: it is off its owner’s queue and hears from a Sequence until it raises a hand again. | `working` by [Lead.assign](/business/nouns/lead/assign); `disqualified` by [Lead.disqualify](/business/nouns/lead/disqualify) |
| `converted` | It fits an Offer: a Deal is open for it, or it bought on its own; the Customer record carries on. | None: it ends here. |
| `disqualified` | It fits no Offer, for the reason recorded; its Contact record stays. | None: it ends here. |

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Lead.assign](/business/nouns/lead/assign) | Assign gives a Lead one owner Worker, by round robin, territory or ICP fit, as the Startup’s routing Policy says. | [Sales Lead](/agents/sales/sales-lead) | [`Lead.assigned`](/business/events/Lead.assigned) | Two-way: `try`, `send`, `do` |
| [Lead.convert](/business/nouns/lead/convert) | Convert ends a qualified Lead’s pursuit as a Lead: it opens a Deal or routes the Lead to self-serve checkout. | [Sales Lead](/agents/sales/sales-lead) | [`Lead.converted`](/business/events/Lead.converted) | Two-way: `try`, `send`, `do` |
| [Lead.disqualify](/business/nouns/lead/disqualify) | Disqualify ends a Lead’s pursuit because it fits no Offer, with the reason; its Contact record and Consent stay. | [Sales Lead](/agents/sales/sales-lead) | [`Lead.disqualified`](/business/events/Lead.disqualified) | Two-way: `try`, `send`, `do` |
| [Waitlist.join](/business/nouns/waitlist/join) | Join adds a Lead to a Waitlist for an Offer that is not open to them. | [Marketing Lead](/agents/marketing/marketing-lead) | [`Waitlist.joined`](/business/events/Waitlist.joined) | None. |
| [Lead.nurture](/business/nouns/lead/nurture) | Nurture takes a Lead that is not ready to buy off its owner’s queue and onto a Sequence, until it raises a hand again. | [Sales Lead](/agents/sales/sales-lead) | [`Lead.nurtured`](/business/events/Lead.nurtured) | Two-way: `try`, `send`, `do` |
| [Lead.qualify](/business/nouns/lead/qualify) | Qualify confirms a Lead matches an Offer’s ICP and opens a Deal for it. | [Sales Engineer](/agents/sales/sales-engineer) | [`Lead.qualified`](/business/events/Lead.qualified) | None. |
| <a id="create"></a>[Lead.create](/business/nouns/lead/create) | Creates a Lead. Inherited from [Noun](/business/nouns/noun). | None. | `Lead.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Lead.get](/business/nouns/lead/get) | Returns one Lead by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Lead.list](/business/nouns/lead/list) | Returns Leads, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Lead.update](/business/nouns/lead/update) | Changes the given properties of a Lead. Inherited from [Noun](/business/nouns/noun). | None. | `Lead.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Lead.delete](/business/nouns/lead/delete) | Deletes a Lead; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Lead.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` |
| --- | --- | --- | --- | --- |
| `Lead.create` | Yes | Yes | Yes | No |
| `Lead.get` | Yes | Yes | Yes | Yes |
| `Lead.list` | Yes | Yes | Yes | Yes |
| `Lead.update` | Yes | Yes | Yes | No |
| `Lead.delete` | Yes | Yes | Yes | No |
| `Lead.assign` | Yes | Yes | Yes | No |
| `Lead.convert` | Yes | Yes | Yes | No |
| `Lead.disqualify` | Yes | Yes | Yes | No |
| `Lead.nurture` | Yes | Yes | Yes | No |
| `Lead.qualify` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Qualify the latest lead with an offer.
```

**API**

```bash
curl -X POST https://api.sb/shiftnote.app/leads/lead_1/qualify \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offer":"offer_1"}'
```

```json
{
  "api": "https://api.sb/shiftnote.app",
  "deal": {
    "$id": "https://api.sb/shiftnote.app/deals/deal_1",
    "$type": "Deal",
    "status": "Open"
  },
  "lead": {
    "$id": "https://api.sb/shiftnote.app/leads/lead_1",
    "$type": "Lead",
    "status": "new"
  },
  "action": {
    "$id": "https://api.sb/shiftnote.app/actions/action_1",
    "operation": "Lead.qualify",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/shiftnote.app/actions/action_1"
  }
}
```

**SDK**

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

const { deal, lead } = await $.Lead.qualify({ lead: 'lead_1', offer: 'offer_1' })
```

**CLI**

```bash
npx startup-builder do Lead.qualify --json '{"lead":"lead_1","offer":"offer_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Lead.qualify({ lead: 'lead_1', offer: 'offer_1' })"
  }
}
```

## Example
A music teacher joins the Waitlist for a lesson-booking [App](/business/nouns/app) and becomes a Lead, with `interest` set to "group lessons". She becomes a Customer when she accepts an Offer.