---
title: "Create interview"
method: POST
path: "/v3/interviews"
tags: ["Interviews"]
---

# Create interview

`POST /v3/interviews`

Schedule an interview against a candidate's application at a specific slot on the job's interview plan. `application_id`, `job_interview_id` (the interview-plan slot), `starts_at`, `ends_at`, and `external_event_id` (the id of the matching event on the organizer's external calendar) are required. Provide the panel via `interviewers`, where each entry must include `response_status` and identify the interviewer by `user_id`, `email`, or `employee_id`. `location` and `video_conferencing_url` are optional metadata copied onto the Greenhouse record; this endpoint records an already-scheduled calendar event rather than creating one on an external calendar.

## Request body

- object
  - `application_id` integer, required
  - `job_interview_id` integer, required
  - `interviewers` union[], required
    - union
      - object
        - `user_id` integer, nullable, required
        - `email` string, email, nullable
        - `employee_id` string, nullable
        - `response_status` 'accepted' | 'declined' | 'tentative' | 'needs_action', required
      - object
        - `user_id` integer, nullable
        - `email` string, email, nullable, required
        - `employee_id` string, nullable
        - `response_status` 'accepted' | 'declined' | 'tentative' | 'needs_action', required
      - object
        - `user_id` integer, nullable
        - `email` string, email, nullable
        - `employee_id` string, nullable, required
        - `response_status` 'accepted' | 'declined' | 'tentative' | 'needs_action', required
  - `starts_at` string, date-time, required
  - `ends_at` string, date-time, required
  - `external_event_id` string, required
  - `location` string, nullable
  - `video_conferencing_url` string, uri, nullable

## Response `201`

Successful

- object
  - `id` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `job_id` integer — Id of the job this interview is on.
  - `application_id` integer — Id of the application this interview is scheduled against. Use it to look up the candidate.
  - `job_interview_id` integer — Id of the job interview slot on the job's interview plan that this interview fulfills. Distinct from this interview's own `id`.
  - `starts_at` string, date-time, nullable — Interview start time, in ISO 8601. `null` for interviews that have not yet been scheduled (for example, assigned take-home tests or interviews awaiting candidate availability) and for all-day events — see `all_day_start_on`.
  - `ends_at` string, date-time, nullable — Interview end time, in ISO 8601. `null` when `starts_at` is also `null`, and for all-day events — see `all_day_end_on`.
  - `location` string, nullable — Free-form location string copied from the calendar event (a room name, an address, or a meeting URL when the customer puts it in the location field). Use `video_conferencing_url` for the link generated by Greenhouse's video integrations.
  - `status` 'to_be_scheduled' | 'scheduled' | 'awaiting_feedback' | 'complete' | 'skipped' | 'collect_feedback' | 'to_be_sent' | 'sent' | 'received' — Lifecycle status of the interview. `to_be_scheduled` is the pre-schedule placeholder; `scheduled` is on the calendar; `awaiting_feedback` is past with scorecards outstanding; `complete` is past with all scorecards in; `collect_feedback` and `skipped` are alternative terminal states; `to_be_sent`, `sent`, and `received` are used for take-home tests sent through Greenhouse.
  - `organizer_id` integer, nullable — Id of the Greenhouse user who scheduled the interview (the organizer on the underlying calendar event). `null` for interviews not yet scheduled through a calendar integration.
  - `scheduled_at` string, date-time, nullable — Timestamp the interview was first placed on a calendar through a Greenhouse calendaring integration (Google, Outlook, or Greenhouse Schedule), in ISO 8601. `null` for interviews that have never been scheduled via the calendar pipeline.
  - `all_day_start_on` string, date, nullable — Start date of an all-day interview, in `YYYY-MM-DD`. Set instead of `starts_at`/`ends_at` when the underlying calendar event is an all-day event. `null` for time-bounded interviews.
  - `all_day_end_on` string, date, nullable — End date of an all-day interview, in `YYYY-MM-DD`. Set instead of `starts_at`/`ends_at` when the underlying calendar event is an all-day event. `null` for time-bounded interviews.
  - `external_event_id` string, nullable — Id of the calendar event on the organizer's calendar (Google Calendar event id, Outlook event id, etc.). Use this to correlate an interview with the event on the external calendar. `null` for interviews not yet pushed to an external calendar.
  - `video_conferencing_url` string, nullable — Join URL for the interview's video conference, auto-populated by Greenhouse's Zoom, Google Meet, or Microsoft Teams integrations when one is attached during scheduling. `null` when no video conferencing was added.
  - `availability_received_at` string, date-time, nullable — Timestamp Greenhouse first recorded availability for this interview's stage on this application (used to compute time-to-schedule), in ISO 8601. `null` if availability has not been collected for the stage.
  - `interviewers` object[]
    - `id` integer
    - `user_id` integer
    - `response_status` 'needs_action' | 'declined' | 'tentative' | 'accepted'
  - `job_interview` object
    - `id` integer
    - `name` string
  - `organizer` object
    - `id` integer
    - `full_name` string
    - `email` string
    - `employee_id` string, nullable

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `422` — Unprocessable Content

---

[API](https://skmtc.dev/greenhouse/apis/auth-api.md) · [All operations](https://skmtc.dev/greenhouse/apis/auth-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/greenhouse/auth-api/revisions/9517a2e54640/schema)