Send an interview

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).

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

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')

{
  "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

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

2. Send the interview

Email the candidate a screening invitation containing their apply link.

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`

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.

Generate an apply link (no email)

staplehire candidates interview-link <candidateId> --design <designId>

{ "interview_link": "https://app.staplehire.com/apply/…" }

Extract just the link:

staplehire candidates interview-link <candidateId> --design <designId> | jq -r '.interview_link'

List and inspect designs

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.

staplehire sessions list <roleId>
staplehire sessions list <roleId> --candidate-email alex@example.com

{ "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

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.

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.

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.

Get started

Workflows

Automation

Reference

1. Create an interview design

Parameters — `designs create`

2. Send the interview

Parameters — `candidates send-interview`

Generate an apply link (no email)

List and inspect designs

Track interview sessions

Common errors

FAQ

​1. Create an interview design

​Parameters — designs create

​2. Send the interview

​Parameters — candidates send-interview

​Generate an apply link (no email)

​List and inspect designs

​Track interview sessions

​Common errors

​FAQ

1. Create an interview design

Parameters — `designs create`

2. Send the interview

Parameters — `candidates send-interview`

Generate an apply link (no email)

List and inspect designs

Track interview sessions

Common errors

FAQ