Rate limit: 100 requests per minute per API key. Requests over the limit return
429 Too Many Requests.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”).