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

# Ingestion API

> Push candidate data into InterviewFlowAI programmatically to trigger interview invitations.

The Ingestion API allows you to programmatically add candidates to a specific Interviewer pipeline.

## Payload structure

| Field                            | Type   | Required | Description                                                                  |
| -------------------------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `interviewerId`                  | string | ✅ Yes    | The unique ID of the Interviewer to ingest candidates into.                  |
| `status`                         | string | ❌ No     | `shortlisted` or `draft`. Controls onboarding experience.                    |
| `skills`                         | array  | ❌ No     | `["nodejs", "aws", "mongodb"]` array of skills to generate custom questions. |
| `data`                           | array  | ✅ Yes    | Array of candidate objects.                                                  |
| `data[].name`                    | string | ✅ Yes    | Candidate's full name.                                                       |
| `data[].email`                   | string | ✅ Yes    | Candidate's email address.                                                   |
| `data[].additionalFields`        | object | ❌ No     | Custom key-value fields to tag against the candidate (e.g. scores, flags).   |
| `data[].metadata`                | object | ❌ No     | External reference data (e.g. ATS ID, phone number). Not used in scoring.    |
| `data[].metadata.sendEmailAfter` | number | ❌ No     | Hours to delay the invitation email (minimum 1, maximum 96).                 |

## Status routing

| Status        | Behavior                                                                                                                                                        |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shortlisted` | Candidate bypasses the application form and is redirected straight to the interview lobby *(requires Resume Screening and Screening Questions to be disabled)*. |
| `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`        |

## Example request

```bash theme={null}
curl -X POST "https://api.interviewflowai.com/api/external/ingest/candidates" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "status": "shortlisted",
    "interviewerId": "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
        }
      }
    ]
  }'
```

<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").
</Tip>