List Candidates

Retrieve a paginated list of candidates with filtering and search

POST /graphql

List Candidates

cURL

curl --request POST \
  --url https://api.example.com/graphql \
  --header 'Content-Type: application/json' \
  --data '
{
  "organizationId": "<string>",
  "jobId": "<string>",
  "pageNumber": 123,
  "pageSize": 123,
  "search": "<string>",
  "status": "<string>"
}
'

200 OK

{
  "data": {
    "getCandidates": {
      "candidate": {
        "_id": "68f8a4876e6926d93568c8b9",
        "uId": "CAN-6E75E9",
        "fullName": "Meera Iyer",
        "emailAddress": "[e-mail]",
        "phoneNumber": "7676446714",
        "resumeScore": 54.0,
        "skillsFound": ["TypeScript", "Express.js", "MongoDB"],
        "status": null,
        "createdAt": "2025-10-22T09:31:51.371Z"
      }
    }
  }
}

Overview

Retrieve candidates for a specific job and organization with support for pagination, search, and status filtering.

Endpoint

POST /graphql
Content-Type: application/json

GraphQL Query

query getCandidates($input: GetCandidatesInput!) {
  getCandidates(input: $input) {
    candidate {
      _id
      uId
      fullName
      emailAddress
      phoneNumber
      resumeScore
      skillsFound
      status
      createdAt
    }
  }
}

Request Parameters

organizationId · string · required

Filter candidates by organization

jobId · string · required

Filter candidates by job ID

pageNumber · integer · default: 1

Page number (1-based indexing)

pageSize · integer · default: 10

Number of items per page

search · string

Search term for candidate name or email

status · string

Filter by candidate status (e.g., “Active”, “Rejected”, “Hired”)

Request Example

cURL

curl -X POST https://api.exterview.ai/graphql \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query getCandidates($input: GetCandidatesInput!) { getCandidates(input: $input) { candidate { _id uId fullName emailAddress phoneNumber resumeScore skillsFound status createdAt } } }",
    "variables": {
      "input": {
        "organizationId": "ORG45",
        "jobId": "JOB-123",
        "pageNumber": 1,
        "pageSize": 10,
        "search": "meera",
        "status": "Active"
      }
    }
  }'

Response

data · object

Show data properties

getCandidates · object

Show getCandidates properties

candidate · object

Candidate information

Show Candidate Object

_id · string

Database identifier

uId · string

Candidate unique ID (e.g., CAN-6E75E9)

fullName · string

Candidate’s full name

emailAddress · string

Email address

phoneNumber · string

Phone number

resumeScore · number

Resume match score (0-100)

skillsFound · array

Array of skills identified from resume

status · string

Current candidate status

createdAt · string

ISO 8601 timestamp of creation

Response Example

200 OK

{
  "data": {
    "getCandidates": {
      "candidate": {
        "_id": "68f8a4876e6926d93568c8b9",
        "uId": "CAN-6E75E9",
        "fullName": "Meera Iyer",
        "emailAddress": "[e-mail]",
        "phoneNumber": "7676446714",
        "resumeScore": 54.0,
        "skillsFound": ["TypeScript", "Express.js", "MongoDB"],
        "status": null,
        "createdAt": "2025-10-22T09:31:51.371Z"
      }
    }
  }
}