> ## 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.

# List Candidates

> Fetch Candidates, their interviews and results, with filters.

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.

> [!NOTE]
>
> **Rate limit:** 60 requests per minute per API key. Requests over the limit return `429 Too Many Requests`.

## Request body fields

**jobId** `string` *required*

The unique ID of the Interviewer to fetch candidates from.

**page** `integer` (default: 1)

Page number. Minimum `1`.

**limit** `integer` (default: 20)

Results per page. Minimum `1` and maximum `100`.

**interviewId** `string`

Fetch a single Candidate by their unique interview ID.

**interviewStatus** `string`

Filter Candidates by interview status.

**additionalFields** `object`

Filter by one or more custom fields. Values can be strings, numbers, or booleans.

**tagFilter** `object`

Filter by one or more tags. Values can be strings, numbers, booleans, or non-empty arrays of those types.

The request body does not accept fields other than those listed above. Keys in `additionalFields` and `tagFilter` must contain at least one non-whitespace character, and each object must contain at least one property.

## Ways to fetch

* **Paginated**: send `jobId`, `page` and `limit`.
* **One Candidate**: send `jobId` and `interviewId`.
* **Custom field filters**: send `additionalFields`. 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 and boolean values**: Returns candidates where the field value exactly matches the supplied value.
* **Status and tag filters**: send `interviewStatus` or `tagFilter`.

```bash Paginated 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 '{
    "jobId": "9786b00b-d110-454f-9e6f-1732daec8916",
    "page": 1,
    "limit": 20
  }'
```

```bash One Candidate 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 '{
    "jobId": "9786b00b-d110-454f-9e6f-1732daec8916",
    "interviewId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }'
```

```bash Custom field filters 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 '{
    "jobId": "9786b00b-d110-454f-9e6f-1732daec8916",
    "page": 1,
    "limit": 20,
    "additionalFields": {
      "score": 50,
      "review": "yes"
    }
  }'
```

```bash Status and tag filters 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 '{
    "jobId": "9786b00b-d110-454f-9e6f-1732daec8916",
    "interviewStatus": "completed",
    "tagFilter": {
      "department": ["Engineering", "Product"],
      "requiresReview": true
    }
  }'
```

## Response

```json 200 theme={null}
{
  "data": {
    "interviews": [
      {
        "starRating": null,
        "id": "480f9248-39f2-4e48-afb7-5925e8f8c07e",
        "jobId": "9786b00b-d110-454f-9e6f-1732daec8916",
        "candidateName": "Jane Doe",
        "candidateEmail": "jane@example.com",
        "source": "api",
        "interviewType": "web_call",
        "phoneNumber": null,
        "status": "completed",
        "interviewScore": 82,
        "resumeFeedback": {
          "candidate_name": "Jane Doe",
          "criteria_results": [
            {
              "score": 4,
              "reason": "The Candidate has relevant experience.",
              "weight": 5,
              "criterion_name": "Relevant experience"
            }
          ],
          "dealbreaker_results": [
            {
              "reason": "The Candidate meets the requirement.",
              "status": "Pass",
              "dealbreaker_text": "Minimum required experience"
            }
          ],
          "overall_score_percentage": 75,
          "overall_dealbreaker_status": "Pass"
        },
        "portFolioFeedback": {
          "overall_score_100": 70
        },
        "portfolioUrl": "https://example.com/portfolio",
        "transcript": "20-AI Interviewer: ...",
        "recordingUrl": "https://example.com/recording.mp4",
        "resume_score": 75,
        "portfolio_score": 70,
        "interview_feedback": {
          "job_title": "Account Executive",
          "red_flags": [],
          "tag_answers": [
            {
              "value": ["5+"],
              "tag_name": "Years Of Experience"
            }
          ],
          "recommendation": "yes",
          "overall_score_100": 82,
          "strengths_timestamps": [
            "128s: The Candidate gave a specific example."
          ],
          "communication_assessment": {
            "grammar_and_syntax": {
              "score": 4,
              "feedback": "The Candidate used clear sentence structures."
            },
            "conversational_flow": {
              "score": 4,
              "feedback": "The Candidate maintained a coherent conversation."
            },
            "vocabulary_and_expression": {
              "score": 4,
              "feedback": "The Candidate used precise professional language."
            },
            "communication_effectiveness": {
              "score": 4,
              "feedback": "The Candidate explained their experience clearly."
            }
          },
          "risks_or_gaps_timestamps": [],
          "notes_for_human_interviewer": [],
          "custom_questions_with_answers_timestamps": [
            {
              "score": 4,
              "answer": "I reviewed the pipeline weekly and prioritized high-intent opportunities.",
              "question": "How do you prioritize your pipeline?",
              "reasoning": "The answer describes a clear process and relevant actions.",
              "timestamp": "128s:",
              "weight_used": 5
            }
          ]
        },
        "customFields": [
          {
            "id": "screening_question_id",
            "type": "yesno",
            "answer": "Yes",
            "question": "Are you legally authorized to work in this country?"
          }
        ],
        "shortlistTimeInMillis": 1786341452787,
        "interviewExpiryTimeInMillis": 1786946252787,
        "recruiterNotes": "Strong communication skills.",
        "csvMetaData": {},
        "trustScoreMetadata": {},
        "tagAnswers": [
          {
            "tag_name": "Years Of Experience",
            "value": ["5+"]
          }
        ],
        "postInterviewAnswers": [
          {
            "answer": "https://example.com/submission",
            "question": "Submit your work sample",
            "questionId": "screening_question_id"
          }
        ],
        "retakeCount": 1,
        "candidateAdditionalFields": {
          "location": "New York"
        },
        "createdAt": "2026-08-07T05:52:44.794684+00:00",
        "updatedAt": "2026-08-10T05:57:32.78728+00:00",
        "retakeAttempts": [
          {
            "id": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
            "interviewId": "480f9248-39f2-4e48-afb7-5925e8f8c07e",
            "jobId": "9786b00b-d110-454f-9e6f-1732daec8916",
            "candidateName": "Jane Doe",
            "candidateEmail": "jane@example.com",
            "attemptNumber": 1,
            "status": "completed",
            "overall_score_100": 85,
            "interview_feedback": {
              "overall_score_100": 85
            },
            "customQuestions": [],
            "transcript": "20-AI Interviewer: ...",
            "originalTranscript": "20-AI Interviewer: ...",
            "recordingUrl": "https://example.com/retake-recording.mp4",
            "customFields": {},
            "trustScoreMetadata": {},
            "tagAnswers": [],
            "completedAt": "2026-08-10T05:50:00.000000+00:00",
            "createdAt": "2026-08-10T05:30:00.000000+00:00",
            "updatedAt": "2026-08-10T05:57:32.78728+00:00"
          }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 22,
      "totalPages": 2,
      "hasNextPage": true,
      "hasPreviousPage": false
    }
  },
  "code": 200,
  "message": "Interviews fetched successfully"
}
```

This example shows every field that can be returned. Fields without a value are omitted, except nullable fields such as `starRating` and `phoneNumber`. `tagAnswers` can be an object or an array depending on the stored tag data. `retakeAttempts` is included only when you provide `interviewId`.

The top-level `code` contains the HTTP-equivalent status code. The `message` describes the result. The `data.interviews` array contains Candidate records, and `data.pagination` describes the current result page.

> [!NOTE]
>
> Feedback fields depend on the Candidate's progress. For example, `interviewScore`, `transcript`, `recordingUrl`, and `interview_feedback` are normally available after the interview is complete. `shortlistTimeInMillis`, `interviewExpiryTimeInMillis`, `csvMetaData`, `postInterviewAnswers`, and `retakeAttempts` appear only when relevant.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.