Skip to main content
GET
/
candidates
List candidates
curl --request GET \
  --url https://api.instaview.sk/candidates \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "John",
      "lastName": "Doe",
      "status": "APPLIED",
      "createdAt": "2025-11-20T10:30:00Z",
      "updatedAt": "2025-11-20T10:30:00Z",
      "jobId": "987e6543-e21b-12d3-a456-426614174000",
      "jobIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "email": "john.doe@example.com",
      "phoneNumber": "+421915123456",
      "gdprExpiryDate": "2026-11-16",
      "overallRating": 85,
      "metadata": {
        "source": "LinkedIn",
        "externalId": "CAND-12345"
      },
      "analysisCount": 2,
      "interviewCount": 3,
      "links": {
        "analyses": "/v1/public/candidates/123e4567-e89b-12d3-a456-426614174000/analyses",
        "interviews": "/v1/public/candidates/123e4567-e89b-12d3-a456-426614174000/interviews"
      },
      "gender": "female",
      "anonymizedCvText": "[NAME]\nSoftware Engineer\nExperience: ..."
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20,
  "totalPages": 8
}
Lists all candidates whose jobs belong to the API key’s company, with pagination and filtering support.

​
Overview

The list candidates endpoint allows you to retrieve candidates across all jobs in your company. You can filter by job, status, search by name or email, and paginate through results. This is useful for managing your candidate pipeline and finding candidates before scheduling interviews.

​
Use Cases

  • Candidate Pipeline Management: Review all candidates across jobs
  • Job-Specific Filtering: Find candidates for a specific job
  • Status Tracking: Filter candidates by recruitment status
  • Search: Locate candidates by name or email

​
Basic Usage

// List all candidates (first page, 20 items)
GET /candidates

​
With Filters

// Filter by job
GET /candidates?jobId=job-uuid

// Filter by status
GET /candidates?status=INTERVIEWING

// Search by name or email
GET /candidates?search=jane@example.com

// Combine filters with pagination
GET /candidates?jobId=job-uuid&status=APPLIED&page=1&limit=50

​
Company Scoping

All returned candidates are associated with jobs that belong to your API key’s company. Candidates from other companies are automatically filtered out.

Candidates Resource Guide

Learn about candidate management, status workflows, and filtering options

Pagination Guide

Understand pagination best practices

Get Candidate

Retrieve a specific candidate by ID

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Query Parameters

​
page
integer
default:1

Page number (1-based)

Required range: 1 <= x <= 10000
Example:

1

​
limit
integer
default:20

Number of items per page

Required range: 1 <= x <= 100
Example:

20

​
companyId
string<uuid>

Company ID (required for ATS keys, optional for regular keys)

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
jobId
string<uuid>

Filter by job ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
status
enum<string>

Filter by candidate status

Available options:
UNDEFINED,
APPLIED,
IN_PROCESS,
REJECTED,
ACCEPTED
Example:

"APPLIED"

​
search
string

Search by name (first or last name)

Example:

"John"

Response

200 - application/json
​
data
object[]
required

Array of candidates

​
total
number
required

Total number of items

Example:

150

​
page
number
required

Current page number

Example:

1

​
limit
number
required

Number of items per page

Example:

20

​
totalPages
number
required

Total number of pages

Example:

8