Schedule interviews and read their scorecards

An interview invites a candidate to book a slot with one or more interviewers. JOIN sends the invitation; the candidate picks a time through a booking link. These endpoints need revision 2026-11-17. All example IDs are fictional; replace them with your own IDs.

1. Choose the interviewers or a template

Interviewers are company users. Read List users and use a user's id, or send their email. Each interviewer needs access to the job and a connected calendar.

To reuse a setup your recruiters already maintain, read List interview templates with status=ACTIVE. A template supplies the title, duration, location, booking window, interviewers and scorecard. Its interviewer pools also apply, though the response does not list them.

curl --fail-with-body "https://api.join.com/v3/interview-templates?status=ACTIVE" \
  -H "Authorization: Bearer $JOIN_API_TOKEN" \
  -H "Join-Version: 2026-11-17"

To attach a scorecard of your choice instead, read List scorecard templates and use its id as scorecardTemplateId.

2. Create the interview

The candidate needs exactly one application to the job, and the job must not be archived. With a template, send only what differs from it:

curl --fail-with-body "https://api.join.com/v3/interviews" \
  -H "Authorization: Bearer $JOIN_API_TOKEN" \
  -H "Join-Version: 2026-11-17" \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{
  "candidateId": 7788,
  "jobId": 4321,
  "interviewTemplateId": "01JB2Z6Q8H6V4M3N2P1R0S9T8U",
  "scheduling": {
    "type": "BOOKING_LINK"
  }
}'

Without a template, send the title, interviewers, duration and location:

{
  "candidateId": 7788,
  "jobId": 4321,
  "title": "Technical interview",
  "interviewers": [
    { "userId": 1234 },
    { "email": "[email protected]" }
  ],
  "durationMinutes": 45,
  "scheduling": {
    "type": "BOOKING_LINK",
    "bookingWindowDays": 7
  },
  "location": {
    "type": "REMOTE",
    "conferencingProvider": "GOOGLE_MEET"
  },
  "scorecardTemplateId": 77
}
  • The candidate is emailed right away. Creating an interview sends a real invitation. The booking link is never returned by the API.
  • The first interviewer is the organizer. A conferencing provider must be one the organizer has connected. Use CUSTOM with a meetingUrl for any other meeting link.
  • A sent location, scheduling or interviewers replaces the template's value whole. It is not merged with it.
  • The booking window counts from the day after creation, 1 to 21 days, 14 by default. If no interviewer has a free slot in it, the request fails with validation_error on scheduling.bookingWindowDays.

See Create an interview for every field and error.

3. Follow the interview

Save data.id from the response, then read the interview with Get an interview, or keep a list in sync with List interviews and updatedAfter:

curl --fail-with-body "https://api.join.com/v3/interviews?candidateId=7788&sort=startsAt" \
  -H "Authorization: Bearer $JOIN_API_TOKEN" \
  -H "Join-Version: 2026-11-17"
statusMeaning
PENDINGWaiting for the candidate to book. startsAt, endsAt and the interviewers' responseStatus are null. It stays PENDING after bookingExpiresAt.
SCHEDULEDBooked, including rescheduled interviews. It stays SCHEDULED after it ends until it is marked COMPLETED or NO_SHOW in JOIN.
CANDIDATE_DECLINEDThe candidate declined the invitation.
CANCELEDCanceled; cancellation.canceledBy says whether by the CANDIDATE or the COMPANY.
COMPLETED, NO_SHOWMarked in JOIN after the interview.

A PENDING interview has no start time, so the startsAfter and startsBefore filters never match it. For an interview staffed only from interviewer pools, interviewers stays empty until the candidate books. The meeting link (location.meetingUrl) appears once the provider creates it after booking.

4. Read the scorecards

Interviewers write their feedback in JOIN. Read it with List candidate scorecards and match each scorecard to its interview by interviewId:

curl --fail-with-body "https://api.join.com/v3/scorecards?candidateId=7788" \
  -H "Authorization: Bearer $JOIN_API_TOKEN" \
  -H "Join-Version: 2026-11-17"

A scorecard's attribute id matches the attribute on its scorecard template. Questions are copied onto each scorecard with their own IDs, so match questions by their text.