> ## Documentation Index
> Fetch the complete documentation index at: https://staplehire.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Send an interview

> Create an AI interview design for a role with the Staplehire CLI, send the screening invite to a candidate by email, or generate an apply link.

An **interview design** is the AI screening script for a role. Generate one, then either email the invite to a candidate (`send-interview`) or generate an apply link without sending email (`interview-link`).

```bash theme={null}
DESIGN_ID=$(staplehire designs create <roleId> --type structured | jq -r '.interview_design.id')
staplehire candidates send-interview <candidateId> --design "$DESIGN_ID"
```

## 1. Create an interview design

```bash theme={null}
DESIGN_ID=$(staplehire designs create <roleId> \
  --type structured \
  --brief "Async screen for backend fundamentals and system design." \
  --round-title "Backend screen" \
  | jq -r '.interview_design.id')
```

```json theme={null}
{
  "interview_design": {
    "id": "design_…",
    "role_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "structured",
    "round_title": "Backend screen"
  }
}
```

### Parameters — `designs create`

| Flag                    | Required | Description                                |
| ----------------------- | -------- | ------------------------------------------ |
| `<roleId>`              | Yes      | Role the design belongs to                 |
| `--type <type>`         | No       | `structured` (default) or `conversational` |
| `--brief <text>`        | No       | Focus areas for the AI interviewer         |
| `--round-title <title>` | No       | Round label shown to the candidate         |

<Note>
  `--type` only accepts `structured` or `conversational`. Any other value fails with exit code `8` (CLI usage).
</Note>

## 2. Send the interview

Email the candidate a screening invitation containing their apply link.

```bash theme={null}
staplehire candidates send-interview <candidateId> --design <designId>
```

### Parameters — `candidates send-interview`

| Flag                  | Required | Description                               |
| --------------------- | -------- | ----------------------------------------- |
| `<candidateId>`       | Yes      | Candidate to invite                       |
| `--design <designId>` | Yes      | Interview design ID from `designs create` |
| `--mode <mode>`       | No       | Delivery mode; defaults to `email`        |

<Tip>
  To get a link **without** sending an email, use `candidates interview-link` (below) rather than a `--mode` value. That's the supported way to retrieve a shareable apply link.
</Tip>

## Generate an apply link (no email)

```bash theme={null}
staplehire candidates interview-link <candidateId> --design <designId>
```

```json theme={null}
{ "interview_link": "https://app.staplehire.com/apply/…" }
```

Extract just the link:

```bash theme={null}
staplehire candidates interview-link <candidateId> --design <designId> | jq -r '.interview_link'
```

## List and inspect designs

```bash theme={null}
staplehire designs list <roleId>      # all designs on a role
staplehire designs get <designId>     # one design
```

## Track interview sessions

Sessions appear once candidates start completing screening. They're empty until then.

```bash theme={null}
staplehire sessions list <roleId>
staplehire sessions list <roleId> --candidate-email alex@example.com
```

```json theme={null}
{ "bundles": [ … ] }
```

## Common errors

| Error                       | Exit code | Fix                                                                 |
| --------------------------- | --------- | ------------------------------------------------------------------- |
| `interview_design_required` | `3`       | Create a design with `designs create` first                         |
| `ValidationError`           | `3`       | Missing `--design` — pass the ID from `designs create`              |
| `NotFoundError`             | `4`       | Wrong candidate or design ID — use `candidates get` / `designs get` |
| CLI usage                   | `8`       | `--type` must be `structured` or `conversational`                   |

## FAQ

<AccordionGroup>
  <Accordion title="Do I need a design before sending an interview?">
    Yes. Create one with `staplehire designs create`, then pass its ID to `send-interview` or `interview-link`.
  </Accordion>

  <Accordion title="How do I get a link instead of emailing the candidate?">
    Use `staplehire candidates interview-link <candidateId> --design <designId>`. It returns `interview_link` without sending an email.
  </Accordion>

  <Accordion title="What are the deprecated aliases?">
    `interview-design` is a deprecated alias for `designs`, and `interview-sessions` is a deprecated alias for `sessions`. Both still work.
  </Accordion>
</AccordionGroup>

Related: [Add a candidate](/docs/add-candidate-cli) · [Send an email](/docs/send-email-cli) · [Command reference](/docs/commands)