Ingestion API - InterviewFlowAI Knowledge Base

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

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
        }
      }
    ]
  }'

Best Practice: Trigger this API call automatically when a candidate reaches a specific stage in your ATS (e.g. “Phone Screen” or “AI Interview”).