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
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.
