Interview Link API - InterviewFlowAI Knowledge Base

Use the Interview Link API when your system should create an interview for one candidate at a time and handle candidate communication itself. This endpoint creates the interview record and returns the direct interview link. InterviewFlowAI does not send or schedule an invitation email for this flow.

Endpoint

POST https://api.interviewflowai.com/api/external/ingest/candidate

All requests must include your API key.

X-API-KEY: your_api_key_here
Content-Type: application/json

Request body fields

Field	Type	Required	Description
`name`	string	Yes	Candidate’s full name. Blank names are rejected.
`email`	string	Yes	Candidate’s email address. The value is normalized to lowercase.
`jobId`	string	Yes	The unique ID of the Interviewer/job to create the interview under.
`status`	string	No	`shortlisted` or `draft`. If omitted, public Interviewers default to `shortlisted` and private Interviewers default to `draft`.
`resumeUrl`	string	No	A publicly accessible URL to the candidate’s resume (PDF). InterviewFlowAI downloads and stores the file.
`skills`	array	No	Skill names used to generate skill-based custom interview questions.
`customQuestions`	array	No	Candidate-specific custom questions to attach to the interview.
`additionalFields`	object	No	Custom candidate fields configured in InterviewFlowAI.
`metadata`	object	No	External reference data such as ATS IDs or phone number.

Example request

curl -X POST "https://api.interviewflowai.com/api/external/ingest/candidate" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "jobId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "status": "shortlisted",
    "metadata": {
      "externalCandidateId": "candidate_12345"
    }
  }'

Example response

{
  "data": {
    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "jobId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "status": "shortlisted",
    "createdAt": "2026-07-01T10:30:00.000Z",
    "interviewLink": "https://app.interviewflowai.com/form?interviewId=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  },
  "code": 201,
  "message": "Interview link created successfully"
}

Behavior

Scenario	Behavior
Candidate already has an interview for the same Interviewer	The request is rejected and no new interview is created.
`status` is `shortlisted`	The returned link takes the candidate directly to the interview flow.
`status` is `draft`	The interview is created as a draft candidate record.
Interviewer is public and `status` is omitted	The interview is created as `shortlisted`.
Interviewer is private and `status` is omitted	The interview is created as `draft`.

Use this endpoint when your ATS, CRM, or internal system should decide how and when to share the interview link with the candidate.