Skip to main content
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

FieldTypeRequiredDescription
interviewerIdstring✅ YesThe unique ID of the Interviewer to fetch candidates from.
pagenumber❌ NoPage number for paginated results.
limitnumber❌ NoNumber of results per page.
interviewIdstring❌ NoFetch a single candidate by their unique interview ID.
additionalFieldsobject❌ NoFilter 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"
    }
  }'