> ## 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 Candidates in bulk

> Invite up to 50 Candidates to one Interviewer in one request.

Use this API to invite up to 50 candidates to one Interviewer in a single request. InterviewFlowAI creates an interview for each candidate and emails them their invitation, either right away or after a delay you choose.

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

## Payload structure

**jobId** `string` *required*

The UUID of the Interviewer to invite Candidates to. The Interviewer must belong to your Company. If the Interviewer is archived, the interviews are still created but no invitation emails are sent.

**status** `string`

`shortlisted` or `draft`. Controls the onboarding experience.

**data** `object[]` *required*

Candidates to invite. Minimum 1 and maximum 50 per request.

**name** `string` *required*

Candidate's full name, 1–255 characters.

**email** `string` *required*

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

**skills** `string[]`

Skills used to generate skill-based questions for this Candidate, such as `nodejs`, `aws`, and `mongodb`.

**customQuestions** `object[]`

Candidate-specific questions. Each item needs `question` and `evaluationCriteria` (`lookingFor`, `strongAnswer`, `weakAnswer`, `weight` 1–10, `maxFollowup` 0–2, and optional `maxDuration` 0.5–10 minutes).

**additionalFields** `object`

Custom key-value fields to tag against the Candidate, such as scores or flags.

**metadata** `object`

External reference data, such as an ATS ID or phone number. This data is not used in scoring. The keys `teamtailor`, `ashby`, `workable` and `recruitcrm` are reserved for built-in integrations and are removed from API requests.

**sendEmailAfter** `number`

Whole number of hours to delay the invitation email. Minimum `1` and maximum `96`. Omit to send immediately.

## Status routing

| Status | Behavior |
| - | - |
| `shortlisted` | Candidate bypasses the application form and is redirected straight to the interview lobby. |
| `draft` | Candidate must fill out the application form. Your team will then need to manually shortlist them from the dashboard. |

### Default behavior (when status is omitted)

| Interviewer Visibility | Default Status |
| - | - |
| Public Interviewer | `shortlisted` |
| Private Interviewer | `draft` |

```bash cURL theme={null}
curl -X POST "https://api.interviewflowai.com/api/external/ingest/interview" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "status": "shortlisted",
    "jobId": "304c0cfb-324f-4b2c-ac89-c93725c00399",
    "data": [
      {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "skills": ["nodejs", "aws", "mongodb"],
        "additionalFields": {
          "Manual Score": 72,
          "isSynced": "true"
        },
        "metadata": {
          "External ID": "candidate_12345",
          "Phone": "+1-555-123-4567",
          "sendEmailAfter": 1
        }
      }
    ]
  }'
```

## Response

The endpoint returns `201 Created` when at least one Candidate is invited, otherwise `200 OK`. Each Candidate appears in one of three lists.

```json 201 theme={null}
{
  "data": {
    "successful": [
      {
        "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "jobId": "304c0cfb-324f-4b2c-ac89-c93725c00399",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "status": "shortlisted",
        "createdAt": "2026-07-01T10:30:00.000Z",
        "interviewLink": "https://app.interviewflowai.com/form?interviewId=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      }
    ],
    "failed": [
      { "index": 1, "name": "Sam", "email": "sam@example", "reason": "Invalid email format" }
    ],
    "duplicates": [
      { "name": "Jane Doe", "email": "jane.doe@example.com", "reason": "Duplicate email found in request payload" }
    ]
  },
  "code": 201,
  "message": "Interview ingest completed: 1 successful, 1 failed, 1 duplicates"
}
```

| List | Contains |
| - | - |
| `successful` | Candidates whose interview was created. |
| `failed` | Candidates that could not be processed, with a `reason`. |
| `duplicates` | Emails repeated in the request, or Candidates who already have an interview for this Interviewer. |

> [!TIP]
>
> **Best Practice:** Trigger this API call automatically when a candidate reaches a specific stage in your ATS (e.g. "Phone Screen" or "AI Interview").


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