# Candidate

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

> A Candidate is a Person under consideration for an Opening, with the graded Evidence for and against them.

A Candidate is a [Person](/business/nouns/person) under consideration for an [Opening](/business/nouns/opening), with the graded [Evidence](/business/nouns/evidence) for and against them.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `opening` | [Opening](/business/nouns/opening) | Yes | The Opening the Person is considered for. |
| `person` | [Person](/business/nouns/person) | Yes | The Person, whose record crosses Startups only with Consent. |
| `source` | `string` | Yes | One of `pool`, `prospecting`, `listing`, or `referral`. |
| `state` | `string` | Yes | One of `screening`, `tryout`, `proposed`, `hired`, or `declined`. |
| `delta` | `json` | No | The per-Verb difference between the Candidate and the incumbent Agent in the tryout. |

## Object
```json
{
  "$id": "https://api.sb/ledgerlark.com/candidates/candidate_1",
  "$type": "Candidate",
  "opening": "opening_1",
  "person": "person_1",
  "source": "pool",
  "state": "screening",
  "delta": {}
}
```

## Relationships
- <a id="rel-applies-to"></a>A Candidate **applies to** one [Opening](/business/nouns/opening): Candidates for an [Opening](/business/nouns/opening) are screened only on what its [Hypothesis](/business/nouns/hypothesis) still lacks. `appliesTo`, inverse [`candidates`](/business/nouns/opening#rel-candidates).
- <a id="rel-presents"></a>A Candidate **presents** one [Person](/business/nouns/person): a Candidate is one [Person](/business/nouns/person)’s candidacy; the Person’s record crosses [Startups](/business/nouns/startup) only with [Consent](/business/nouns/consent). `presents`, inverse [`candidacies`](/business/nouns/person#rel-candidacies).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Candidate.screen](/business/nouns/candidate/screen) | Screen asks a Candidate only what the Opening’s Hypothesis still lacks, in writing, and grades each answer as Evidence. | [Recruiter](/agents/people/recruiter) | [`Candidate.screened`](/business/events/Candidate.screened) | None. |
| <a id="create"></a>[Candidate.create](/business/nouns/candidate/create) | Creates a Candidate. Inherited from [Noun](/business/nouns/noun). | None. | `Candidate.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Candidate.get](/business/nouns/candidate/get) | Returns one Candidate by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Candidate.list](/business/nouns/candidate/list) | Returns Candidates, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Candidate.update](/business/nouns/candidate/update) | Changes the given properties of a Candidate. Inherited from [Noun](/business/nouns/noun). | None. | `Candidate.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Candidate.delete](/business/nouns/candidate/delete) | Deletes a Candidate; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Candidate.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` |
| --- | --- | --- | --- | --- |
| `Candidate.create` | Yes | Yes | Yes | No |
| `Candidate.get` | Yes | Yes | Yes | Yes |
| `Candidate.list` | Yes | Yes | Yes | Yes |
| `Candidate.update` | Yes | Yes | Yes | No |
| `Candidate.delete` | Yes | Yes | Yes | No |
| `Candidate.screen` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Screen the candidate Rosa Ibarra.
```

**API**

```bash
curl -X POST https://api.sb/patentpad.com/candidates/candidate_1/screen \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/patentpad.com",
  "candidate": {
    "$id": "https://api.sb/patentpad.com/candidates/candidate_1",
    "$type": "Candidate",
    "opening": "opening_1",
    "person": "person_1",
    "source": "pool",
    "state": "screening"
  },
  "action": {
    "$id": "https://api.sb/patentpad.com/actions/action_1",
    "operation": "Candidate.screen",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/patentpad.com/actions/action_1"
  }
}
```

**SDK**

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

const candidate = await $.Candidate.screen({ candidate: 'candidate_1' })
```

**CLI**

```bash
npx startup-builder do Candidate.screen --json '{"candidate":"candidate_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Candidate.screen({ candidate: 'candidate_1' })"
  }
}
```

## Example
A Candidate for a `cofounder` Opening at a clinic-scheduling API arrives from the talent pool with shipped work from a past [Startup](/business/nouns/startup). Her tryout closes three clinic-group deals the [Sales Lead](/agents/sales/sales-lead) [Agent](/business/nouns/agent) had stalled on, so her state moves to `proposed`.