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
CUSTOMwith ameetingUrlfor any other meeting link. - A sent
location,schedulingorinterviewersreplaces 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_erroronscheduling.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"status | Meaning |
|---|---|
PENDING | Waiting for the candidate to book. startsAt, endsAt and the interviewers' responseStatus are null. It stays PENDING after bookingExpiresAt. |
SCHEDULED | Booked, including rescheduled interviews. It stays SCHEDULED after it ends until it is marked COMPLETED or NO_SHOW in JOIN. |
CANDIDATE_DECLINED | The candidate declined the invitation. |
CANCELED | Canceled; cancellation.canceledBy says whether by the CANDIDATE or the COMPANY. |
COMPLETED, NO_SHOW | Marked 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.