Create, read, reassign, reschedule, and cancel live interviews.

Interviews

Create and manage live interview sessions. For a complete integration walkthrough, start with Schedule a live interview.

List interviews

GET /api/v1/interviews · Required scope: interviews:read.

bash

curl --fail-with-body "https://litmushiring.com/api/v1/interviews?posting_id=posting_abc123&limit=50" \
  -H "Authorization: Bearer $LITMUS_API_KEY"

json

{
  "interviews": [
    {
      "id": "sess_abc123",
      "posting_id": "posting_abc123",
      "round_id": "step_abc123",
      "track_id": "track_abc123",
      "assessment_id": "asmt_ghi789",
      "candidate": {
        "id": "cand_abc123",
        "email": "candidate@example.com",
        "name": "Sample Candidate"
      },
      "status": "scheduled",
      "source": "litmus",
      "scheduled_start_at": "2026-10-20T17:00:00.000Z",
      "duration_minutes": 60,
      "indefinite": false,
      "time_zone": "America/Los_Angeles",
      "interviewer_email": "interviewer@example.com",
      "meeting_link": "https://video.example.com/room/abc",
      "externally_scheduled": false,
      "call_ended_at": null,
      "canceled_at": null,
      "created_at": "2026-09-20T12:00:00.000Z",
      "updated_at": "2026-09-20T12:00:00.000Z"
    }
  ],
  "next_cursor": null
}

Query parameters

Parameter	Description
`posting_id`	Filter by posting.
`round_id`	Filter by pipeline round.
`candidate_email`	Exact email match, normalized to lowercase.
`from`, `to`	Inclusive ISO 8601 bounds on the stored scheduled start. For an unused external link, the stored value is link creation time even though the public `scheduled_start_at` is `null`.
`updated_since`	Include records updated at or after this ISO 8601 timestamp.
`include_canceled`	Defaults to `true`. Set to `false` to exclude canceled interviews.
`limit`	Page size from 1 to 100. Default: 50.
`cursor`	The previous response's opaque `next_cursor`.

Results are ordered by start time, then ID. Keep filters unchanged when passing next_cursor into the next request. A null cursor marks the final page.

Status

Status	Meaning
`scheduled`	The interview is booked and its session window remains open.
`completed`	The call was ended or its session window closed. This does not guarantee a submission or completed grading.
`canceled`	The interview was canceled and remains available to read.
`pending`	An external session link has not been used.
`expired`	An external session link expired before use.

scheduled_start_at is null for an unused external session link, including one canceled before use. created_at records when the link was created. source identifies the booking origin (litmus, external, or a connected ATS). Interviews imported by an ATS can have externally_scheduled: true and a real scheduled start time.

For indefinite: true, the nominal duration_minutes does not define the session's end. See Synchronize interview changes for cancellation handling and status transitions that occur without a stored update.

Polling for changes

Use updated_since to read stored updates and re-read active interviews to detect time-based status changes. See Synchronize interview changes.

Read one interview

GET /api/v1/interviews/{id} · Required scope: interviews:read.

Returns the interview object directly, with the same fields as each entry in interviews above. Add include to request artifacts.

Read interview transcripts, recording details, and notes

bash

curl --fail-with-body \
  "https://litmushiring.com/api/v1/interviews/sess_abc123?include=transcript,recording,notes" \
  -H "Authorization: Bearer $LITMUS_API_KEY"

`include` value	Additional response object
`transcript`	`transcript` with `text`, `segments`, and `received_at`.
`recording`	`recording` with `available` and `duration_seconds`.
`notes`	`interviewer_notes` with `text` and `updated_at`.

Artifact fields can be null when unavailable. Recordings are playable in the dashboard; the API returns availability and duration, not a playback URL. Unsupported include values return 400.

Book an interview

POST /api/v1/interviews · Required scope: interviews:write.

bash

curl --fail-with-body -X POST https://litmushiring.com/api/v1/interviews \
  -H "Authorization: Bearer $LITMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posting_id": "posting_abc123",
    "round_id": "step_abc123",
    "candidate_email": "candidate@example.com",
    "candidate_name": "Sample Candidate",
    "scheduled_start_at": "2026-10-20T17:00:00Z",
    "interviewer_email": "interviewer@example.com",
    "time_zone": "America/Los_Angeles"
  }'

Request body

Field	Required	Description
`posting_id`	Yes	Posting ID from the roles endpoint or dashboard.
`round_id`	Yes	Pipeline step with `type: "assessment"`, `delivery_mode: "sync"`, and `bookable: true`, in the candidate's track.
`candidate_id`	One candidate identifier	Existing candidate ID for this round's assessment. Takes precedence if both candidate identifiers are provided.
`candidate_email`	One candidate identifier	Reuses a candidate for this assessment or creates one when needed. Creating one adds them to the role and, for a standard booking, the confirmation email carries their assessment link, so `interviews:write` can invite a new candidate this way.
`candidate_name`	No	Name used when creating a candidate.
`scheduled_start_at`	For standard booking	ISO 8601 timestamp with an explicit UTC offset. External-link mode does not use this as an appointment time.
`interviewer_email`	For external scheduling	Recommended for standard bookings. Choose an available interviewer. If omitted, the stored booking has no named interviewer and notifications use the round's configured fallback.
`meeting_link`	For external scheduling	Meeting URL. Standard bookings fall back to the interviewer's configured link, then an automatically created meeting link when calendar integration is configured.
`time_zone`	No	IANA time zone for booking emails, such as `America/Los_Angeles`. Does not replace the timestamp's UTC offset.
`externally_scheduled`	No	Defaults to `false`. Set to `true` to create an external session link without a Litmus calendar event or booking email.
`replace_existing`	No	Defaults to `false`. Set to `true` only to intentionally replace an existing booking.

For standard bookings, read GET /postings/{id}/slots first and use a returned time and interviewer. The booking route currently accepts an unoffered time; it does not use the availability response as a required reservation token. It still refuses a full offered time or an already-booked named interviewer with 409. Keep your request aligned with the availability you showed the user, and refresh it after a conflict.

Response

Returns 201 with an interview object using the fields shown in List interviews. Standard bookings send a candidate confirmation and an interviewer briefing with calendar details. Booking by email does not require a preceding POST /invites request.

Top-level field	Description
`interview`	The created or updated interview. Save its `id`.
`candidate_link`	Returned for external scheduling. Share it with the candidate through your integration.
`warnings`	Present when the booking succeeded but follow-up is needed. Do not repeat the booking to resolve a warning.

Check the returned meeting link before considering the interview ready. If meeting creation failed, add a link from the session page in the dashboard. See External scheduling for the external-link lifecycle and your integration's calendar responsibilities.

An existing non-canceled interview for the candidate causes a 409 unless replace_existing: true is provided. Candidate records are assessment-specific; this does not prevent the same person from participating in multiple rounds. See Errors and retries for other conflicts and retry handling.

Reschedule an interview

Call POST /api/v1/interviews with the original posting_id, round_id, and candidate_id, the new start time, and replace_existing: true. Include the intended interviewer, time zone, and meeting link as appropriate; this is a booking request, not a partial update.

bash

curl --fail-with-body -X POST https://litmushiring.com/api/v1/interviews \
  -H "Authorization: Bearer $LITMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posting_id": "posting_abc123",
    "round_id": "step_abc123",
    "candidate_id": "cand_abc123",
    "scheduled_start_at": "2026-10-21T17:00:00Z",
    "interviewer_email": "interviewer@example.com",
    "time_zone": "America/Los_Angeles",
    "replace_existing": true
  }'

Choose a future available time. Rebooking resets session access and reminders, updates the calendar event, and sends booking emails again. It returns 201 with the booking response described above. Use this only for an intentional reschedule, not an automatic retry.

Change the interviewer for a booking

PATCH /api/v1/interviews/{id} · Required scope: interviews:write.

bash

curl --fail-with-body -X PATCH https://litmushiring.com/api/v1/interviews/sess_abc123 \
  -H "Authorization: Bearer $LITMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"interviewer_email": "someone-else@example.com"}'

Changes the interviewer while keeping the candidate and start time unchanged. For a Litmus calendar event, the attendee is updated and the new interviewer receives a briefing. Returns 200 with the interview object directly, or 409 if the interviewer is already booked at that time.

This endpoint accepts interviewer_email only. Sending scheduled_start_at returns 400; use Reschedule an interview.

Cancel an interview

DELETE /api/v1/interviews/{id} · Required scope: interviews:write.

bash

curl --fail-with-body -X DELETE https://litmushiring.com/api/v1/interviews/sess_abc123 \
  -H "Authorization: Bearer $LITMUS_API_KEY"

Returns 200 with the interview object directly. The interview remains readable with status: "canceled" and its cancellation time in canceled_at.

Litmus deletes its calendar event, which triggers calendar cancellation notifications. It does not send a separate cancellation email. For externally scheduled interviews, cancel the event in your own calendar system as well.

Cancellation is safe to retry: a repeated request returns the canceled interview without changing the original cancellation time.