> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interviewflowai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Interview Link API

> Create one interview and receive the candidate interview link without sending an invitation email.

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

```http theme={null}
POST https://api.interviewflowai.com/api/external/ingest/candidate
```

All requests must include your API key.

```http theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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`.                                  |

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