> ## Documentation Index > Fetch the complete documentation index at: https://docs.instaview.sk/llms.txt > Use this file to discover all available pages before exploring further. # List Candidates > Lists candidates that belong to the API key's company. Includes candidates with job associations and candidates in the candidate pool (no job assignments). 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 ```javascript theme={null} // List all candidates (first page, 20 items) GET /candidates ``` ## With Filters ```javascript theme={null} // 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. ## Related Resources Learn about candidate management, status workflows, and filtering options Understand pagination best practices Retrieve a specific candidate by ID ## OpenAPI ````yaml GET /candidates openapi: 3.0.0 info: title: InstaView API description: |- InstaView API Documentation ## Authentication All endpoints require API key authentication using Bearer token: ``` Authorization: Bearer sk_your_api_key_here ``` ## API Key Management The API Key module provides comprehensive key management for: - **Direct Client Keys**: Company-scoped keys for your applications - **ATS Partner Keys**: Resource-scoped keys for ATS integrations ### Key Features - HMAC-SHA256 hashing for API key storage - Configurable rate limiting - Comprehensive audit logging - Company-level isolation - Resource scoping for ATS partners version: 1.0.0 contact: {} servers: - url: https://api.instaview.sk description: Production API Gateway security: [] tags: [] paths: /candidates: get: tags: - Candidates summary: List candidates description: >- Lists candidates that belong to the API key's company. Includes candidates with job associations and candidates in the candidate pool (no job assignments). operationId: PublicCandidatesController_listCandidates_v1 parameters: - name: page required: false in: query description: Page number (1-based) schema: minimum: 1 maximum: 10000 default: 1 example: 1 type: integer - name: limit required: false in: query description: Number of items per page schema: minimum: 1 maximum: 100 default: 20 example: 20 type: integer - name: companyId required: false in: query description: Company ID (required for ATS keys, optional for regular keys) schema: example: 123e4567-e89b-12d3-a456-426614174000 type: string format: uuid - name: jobId required: false in: query description: Filter by job ID schema: example: 123e4567-e89b-12d3-a456-426614174000 type: string format: uuid - name: status required: false in: query description: Filter by candidate status schema: example: APPLIED type: string enum: - UNDEFINED - APPLIED - IN_PROCESS - REJECTED - ACCEPTED - name: search required: false in: query description: Search by name (first or last name) schema: example: John type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PublicListCandidatesResponseDto' security: - bearer: [] components: schemas: PublicListCandidatesResponseDto: type: object properties: data: description: Array of candidates type: array items: $ref: '#/components/schemas/PublicCandidateDto' total: type: number description: Total number of items example: 150 page: type: number description: Current page number example: 1 limit: type: number description: Number of items per page example: 20 totalPages: type: number description: Total number of pages example: 8 required: - data - total - page - limit - totalPages PublicCandidateDto: type: object properties: id: type: string description: Candidate ID example: 123e4567-e89b-12d3-a456-426614174000 jobId: type: string description: '[Deprecated] Single job ID; use jobIds instead.' deprecated: true example: 987e6543-e21b-12d3-a456-426614174000 jobIds: type: array description: Jobs the candidate is assigned to. items: type: string format: uuid uniqueItems: true maxItems: 50 firstName: type: string description: Candidate's first name example: John lastName: type: string description: Candidate's last name example: Doe email: type: string description: Candidate's email address example: john.doe@example.com phoneNumber: type: string description: Candidate's phone number example: '+421915123456' status: type: string description: Candidate status enum: - UNDEFINED - APPLIED - IN_PROCESS - REJECTED - ACCEPTED example: APPLIED gdprExpiryDate: type: string description: >- GDPR expiry date. Currently returned as a date (no time). NOTE: We plan to migrate to a timestamp with timezone (timestamptz) for global correctness. example: '2026-11-16' format: date overallRating: type: number description: Overall rating/match score (0-100) example: 85 minimum: 0 maximum: 100 metadata: type: object description: Custom metadata example: source: LinkedIn externalId: CAND-12345 createdAt: type: string description: Created timestamp (UTC) example: '2025-11-20T10:30:00Z' format: date-time updatedAt: type: string description: Updated timestamp (UTC) example: '2025-11-20T10:30:00Z' format: date-time analysisCount: type: number description: Number of analyses for this candidate (for quick overview) example: 2 interviewCount: type: number description: Number of interviews for this candidate (for quick overview) example: 3 links: type: object description: >- Convenience links to related collections. Endpoints may be added incrementally. example: analyses: >- /v1/public/candidates/123e4567-e89b-12d3-a456-426614174000/analyses interviews: >- /v1/public/candidates/123e4567-e89b-12d3-a456-426614174000/interviews gender: type: string description: >- Candidate's gender. Used for gender-aware addressing in interviews. Null if not explicitly set (auto-detected from name). enum: - male - female nullable: true example: female anonymizedCvText: type: string description: The candidate's anonymized CV in plain text. example: |- [NAME] Software Engineer Experience: ... workHistory: type: array description: Work history items of the candidate. maxItems: 20 items: $ref: '#/components/schemas/PublicCandidateWorkHistoryItemDto' required: - id - firstName - lastName - status - createdAt - updatedAt PublicCandidateWorkHistoryItemDto: type: object properties: id: type: string description: Work history item ID format: uuid example: 123e4567-e89b-12d3-a456-426614174000 companyName: type: string description: Name of the employer company example: Google minLength: 1 maxLength: 255 candidatePosition: type: string description: Candidate's job position/title example: Software Engineer minLength: 1 maxLength: 255 referenceName: type: string description: Name of the reference person example: Jane Smith maxLength: 255 referencePhone: type: string description: Phone number of reference contact in E.164 format example: '+1987654321' pattern: ^\+[1-9]\d{1,14}$ startDate: type: string description: Job start date in calendar format (yyyy-MM-dd) example: '2020-01-01' format: date pattern: ^\d{4}-\d{2}-\d{2}$ endDate: type: string description: Job end date in calendar format (yyyy-MM-dd) example: '2022-12-31' format: date pattern: ^\d{4}-\d{2}-\d{2}$ required: - companyName - candidatePosition - referencePhone securitySchemes: bearer: type: http scheme: bearer description: API key for authentication using Bearer scheme ````