> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interviewflowai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch API

> Retrieve candidate lists, specific interview details, and filter records directly from InterviewFlowAI.

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.

```bash theme={null}
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.

```bash theme={null}
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"`).

```bash theme={null}
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"
    }
  }'
```