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

# Invite a Candidate

> Invite one Candidate and get their interview link.

Use this API to invite one candidate at a time. The endpoint creates the interview, emails the invitation to the candidate, and returns the direct interview link.

> [!NOTE]
>
> **Rate limit:** 100 requests per minute per API key. Requests over the limit return `429 Too Many Requests`.

## Request body fields

**name** `string` *required*

Candidate's full name. Maximum 255 characters. Blank names are rejected.

**email** `string` *required*

Candidate's email address. The value is normalized to lowercase.

**jobId** `string` *required*

The UUID of the Interviewer to create the interview under. Archived Interviewers are rejected.

**status** `string`

`shortlisted` or `draft`. If omitted, public Interviewers default to `shortlisted` and private Interviewers default to `draft`.

**resumeUrl** `string`

A publicly accessible URL to the Candidate's resume (PDF). InterviewFlowAI downloads the file and stores it as a PDF. If the download fails, the interview is still created, without a resume, and no error is returned.

**skills** `string[]`

Skill names used to generate skill-based custom interview questions. If generation fails, the request returns `500` "Failed to generate skill test questions".

**customQuestions** `object[]`

Candidate-specific custom questions to attach to the interview.

**additionalFields** `object`

Custom Candidate fields configured in InterviewFlowAI.

**metadata** `object`

External reference data such as ATS IDs. `metadata.phoneNumber` sets the Candidate's phone number.

```bash cURL 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"
    }
  }'
```

## Response

```json 201 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. |
| `jobId` doesn't exist or belongs to another Company | `404` "Job not found or does not belong to this account". |
| Interviewer is archived | `400` "Cannot create interviews for archived jobs". |
| `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 also needs the interview link, for example to store it on the candidate record.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.