/api/v2/interviews

Creates an interview for the application in the interview step. Idempotency is automatic and scoped to the authenticated company and this endpoint (POST /interviews): retries with the same JSON request body (object keys and array element order normalized before hashing) within 72 hours replay the stored success response with HTTP 201 instead of creating a duplicate interview. The Idempotency-Key request header is not read and does not affect deduplication. While another request with the same body is in flight, concurrent retries may receive HTTP 409 with message idempotency_request_in_progress and a hint field; use exponential backoff and keep the body unchanged. If any call already returned HTTP 201 for that body, persist that payload and keep retrying with the same body until replay succeeds—do not treat 409 alone as a failed create.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
number
required
≥ 1

Application identifier owned by the authenticated company.

number
required
≥ 1

Job identifier associated with the application.

number
required
≥ 1

Company user who will conduct the interview and owns the calendar used for scheduling operations.

string
required
length between 1 and 255

Interview title shown in the calendar event and triage UI.

string
enum

Calendar provider owned by the interviewer. When omitted, the first connected OAuth provider is used with explicit precedence Google then Microsoft (if both are connected, Google is selected). Matches GET /interview-slots.

Allowed:
string
enum
required

Meeting type. When remote, Meet/Teams link generation is attempted.

Allowed:
string
required

Selected slot start time (ISO-8601 with explicit timezone offset, e.g. Z or ±HH:mm). Must be in the future. The body timezone is used for calendar rendering, not for interpreting this instant. Free/busy is a best-effort check; a race after that check can still return 409 slot_not_available.

string
required

Selected slot end time (ISO-8601 with explicit timezone offset, e.g. Z or ±HH:mm). Must be strictly after startAt.

string
required
length between 1 and 50

IANA timezone used for calendar event creation.

participants
array of objects
required
length ≥ 2

Interview participants invited to the calendar event. At least two are required. Must include a participant with role candidate whose id matches the candidate of the application (resolved from applicationId). Name and email are resolved from the platform (company users and candidate profiles). Company users without a valid name or email are rejected; candidates without a usable email are omitted from the calendar invite.

participants*
number
required
≥ 1

Participant user or candidate identifier.

string
required

Participant role in the interview.

number
required
≥ 1

Participant user or candidate identifier.

string
required

Participant role in the interview.

address
object

Required when meetingType is in-person.

string

Optional calendar event description. May include placeholders resolved by Meeting Scheduler.

Responses

400

Invalid payload, missing application candidate in participants, or a company-user participant without a valid name/email on the platform.

401

Bearer authorization token invalid.

403

User is not allowed to access this endpoint.

404

Feature disabled or application not found for the authenticated company.

422

Calendar provider is not connected, or interview creation failed business rules.

502

Calendar provider is unavailable.

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json