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

​
Payload structure

FieldTypeRequiredDescription
interviewerIdstring✅ YesThe unique ID of the Interviewer to ingest candidates into.
statusstring❌ Noshortlisted or draft. Controls onboarding experience.
skillsarray❌ No["nodejs", "aws", "mongodb"] array of skills to generate custom questions.
dataarray✅ YesArray of candidate objects.
data[].namestring✅ YesCandidate’s full name.
data[].emailstring✅ YesCandidate’s email address.
data[].additionalFieldsobject❌ NoCustom key-value fields to tag against the candidate (e.g. scores, flags).
data[].metadataobject❌ NoExternal reference data (e.g. ATS ID, phone number). Not used in scoring.
data[].metadata.sendEmailAfternumber❌ NoHours to delay the invitation email (minimum 1, maximum 96).

​
Status routing

StatusBehavior
shortlistedCandidate bypasses the application form and is redirected straight to the interview lobby (requires Resume Screening and Screening Questions to be disabled).
draftCandidate 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 VisibilityDefault Status
Public Interviewershortlisted
Private Interviewerdraft

​
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”).