---
title: "Invite a candidate"
method: POST
path: "/api/v1/interviews"
tags: ["Interviews"]
---

# Invite a candidate

`POST /api/v1/interviews`

## Request

- Base URL: `https://app.probbai.com`
- URL: `https://app.probbai.com/api/v1/interviews`
- Auth: HTTP bearer

Create an interview attempt and prepare its questions. ProBB AI can send the invitation email, or your own system can deliver the candidate link.

## Before you call

Obtain a current interview quote and send the same details plus quoteFingerprint with a stable Idempotency-Key. The workspace must have interview allowance.

**Required scope:** `interviews:write`.

## What happens next

A 202 returns interviewId and statusUrl. With sendEmail=true, invitationToken is null. With false, securely deliver /interview/{invitationToken} on the application origin yourself. Preparation and email delivery proceed independently.

## Recovery

Repeat the same body/key after a timeout. A returned token is a bearer credential; never log it. Replays only recover an eligible current pending invitation. Use resend for another email and reinterview for a new attempt.

[Follow the complete workflow](/integration-interviews/) · [Errors and retries](/api-errors/)

## Headers

- `Idempotency-Key` string, required

## Request body

- InterviewInput
  - `reportId` string, required: Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace.
  - `candidateEmail` string, email, required: Email address of the intended candidate. The quote and invitation must use the same address.
  - `sendEmail` boolean: True (default) asks ProBB AI to email the invitation. False returns a private link credential for your system to deliver. Invitation batches require true.
  - `quoteFingerprint` string, required: Fingerprint copied unchanged from the corresponding current quote. Changing quote inputs requires a new quote.

## Response `202`

A 202 returns interviewId and statusUrl. With sendEmail=true, invitationToken is null. With false, securely deliver /interview/{invitationToken} on the application origin yourself. Preparation and email delivery proceed independently.

- object
  - `data` InterviewAdmission, required
    - `interviewId` string, required: Logical interview attempt ID returned by invitation. A reinterview receives a new ID.
    - `reportId` string, required: Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace.
    - `invitationToken` string, nullable, required: Bearer credential returned only when sendEmail is false and the invitation is current and pending; otherwise null.
    - `statusUrl` string, required: Relative API path to poll with the same workspace API key. Resolve against your application origin.
    - `emailDelivery` 'queued' | 'sent' | 'failed' | 'not_requested', required: Email processing state. sent means provider acceptance, not confirmed inbox delivery; not_requested means your system delivers the link.

## Other responses

- `400`: Invalid input or cursor
- `401`: Invalid, expired, or revoked API key
- `403`: Disabled organisation or missing scope
- `404`: The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.
- `405`: Method not allowed; consult Allow for supported methods
- `409`: Repeat the same body/key after a timeout. A returned token is a bearer credential; never log it. Replays only recover an eligible current pending invitation. Use resend for another email and reinterview for a new attempt.
- `422`: Input cannot be processed or workspace allowance/capacity is insufficient. Inspect error.reason before retrying.
- `429`: Request limit exceeded
- `500`: Unexpected failure
- `503`: Service unavailable

---

[API](https://skmtc.dev/probbai/apis/probb-ai-customer-api.md) · [All operations](https://skmtc.dev/probbai/apis/probb-ai-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/probbai/apis/probb-ai-customer-api/revisions/33a3294530e4?raw)