Fetch API - InterviewFlowAI Knowledge Base

The Fetch API allows you to pull candidate and interview data back into your own internal systems. All fetch requests are POST requests with a JSON body.

Request body fields

Field	Type	Required	Description
`interviewerId`	string	✅ Yes	The unique ID of the Interviewer to fetch candidates from.
`page`	number	❌ No	Page number for paginated results.
`limit`	number	❌ No	Number of results per page.
`interviewId`	string	❌ No	Fetch a single candidate by their unique interview ID.
`additionalFields`	object	❌ No	Filter candidates by custom field values (see filtering rules below).

1. Paginated fetch

Retrieve a paginated list of candidates for a specific Interviewer.

curl -X POST "https://api.interviewflowai.com/api/external/fetch/candidates" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "interviewerId": "9786b00b-d110-454f-9e6f-1732daec8916",
    "page": 1,
    "limit": 20
  }'

2. Single candidate fetch

Look up a specific candidate using their unique interview ID.

curl -X POST "https://api.interviewflowai.com/api/external/fetch/candidates" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "interviewerId": "9786b00b-d110-454f-9e6f-1732daec8916",
    "interviewId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }'

3. Custom field filters

Filter your candidate list based on values in additionalFields. Filtering rules:

Numeric values: Returns candidates where the field value is ≥ the specified number (e.g. "score": 50 returns all candidates with score 50 or above).
String values: Returns candidates where the field value exactly matches the string (e.g. "review": "yes").

curl -X POST "https://api.interviewflowai.com/api/external/fetch/candidates" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "interviewerId": "9786b00b-d110-454f-9e6f-1732daec8916",
    "page": 1,
    "limit": 20,
    "additionalFields": {
      "score": 50,
      "review": "yes"
    }
  }'