> ## 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. # Get Candidate > Returns a single candidate, ensuring the candidate (and any job associations) belong to the API key's company. Retrieves a specific candidate by ID, including profile information, status, and associated job details. ## Overview The get candidate endpoint returns complete information about a single candidate, including contact details, status, associated job, and metadata. Use this endpoint to retrieve candidate details before scheduling interviews or updating candidate information. ## Use Cases * **Candidate Profile Display**: Show complete candidate information in your UI * **Pre-Interview Validation**: Verify candidate exists and is accessible before scheduling interviews * **Status Checking**: Check current candidate status in the pipeline * **Integration Validation**: Confirm candidate details match external systems ## Response Data The response includes all candidate information: * Contact details (name, email, phone) * Associated job information * Current status in recruitment pipeline * Gender (if set, used for interview addressing) * Metadata (resume URL, LinkedIn, custom fields) * Timestamps (created, updated) ## Company Isolation You can only access candidates that are associated with jobs in your API key's company. The API validates that the candidate's job belongs to your company before returning the candidate data. ## Error Scenarios * **404 Not Found**: Candidate doesn't exist or has been deleted * **403 Forbidden**: Candidate's job belongs to a different company ## Related Resources Learn about candidate structure and status workflows Modify candidate information Browse all candidates ## OpenAPI ````yaml GET /candidates/{id} 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/{id}: get: tags: - Candidates summary: Get candidate by ID description: >- Returns a single candidate, ensuring the candidate (and any job associations) belong to the API key's company. operationId: PublicCandidatesController_getCandidateById_v1 parameters: - name: id required: true in: path schema: type: string format: uuid - name: companyId required: false in: query description: >- Required for ATS API keys to specify which company to access. Ignored for standard company API keys. schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PublicCandidateDto' security: - bearer: [] components: schemas: 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 ````