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

# Update Candidate

> Updates a candidate that belongs to the API key's company. Only basic profile/contact/status fields are supported.

Updates an existing candidate using partial updates. Only provided fields will be updated; omitted fields remain unchanged.

## Overview

The update candidate endpoint allows you to modify candidate information without recreating the candidate. This supports partial updates, meaning you only need to provide the fields you want to change. Useful for updating contact information, changing status, or adding metadata.

## Use Cases

* **Status Updates**: Move candidates through recruitment pipeline
* **Contact Updates**: Update email, phone, or other contact information
* **Gender Override**: Set or clear candidate gender for accurate interview addressing
* **Job Assignment Management**: Assign candidates to jobs or manage multiple job associations
* **Metadata Updates**: Add or modify custom fields and links
* **Profile Refinement**: Update candidate profile as more information becomes available

## Partial Updates

You can update any combination of fields:

```javascript theme={null}
// Update only status
PATCH /candidates/{id}
{
  "status": "IN_PROCESS"
}

// Update contact information
PATCH /candidates/{id}
{
  "email": "newemail@example.com",
  "phoneNumber": "+1987654321"
}

// Assign to multiple jobs
PATCH /candidates/{id}
{
  "jobIds": ["job-uuid-1", "job-uuid-2", "job-uuid-3"]
}

// Remove all job assignments (move to candidate pool)
PATCH /candidates/{id}
{
  "jobIds": []
}

// Set candidate gender
PATCH /candidates/{id}
{
  "gender": "female"
}

// Clear gender (revert to auto-detection)
PATCH /candidates/{id}
{
  "gender": null
}

// Replace candidate work history
PATCH /candidates/{id}
{
  "workHistory": [
    {
      "companyName": "Tech Corp",
      "candidatePosition": "Senior Software Engineer",
      "referenceName": "Jane Smith",
      "referencePhone": "+1234567890",
      "startDate": "2020-01-01"
    }
  ]
}
```

## Managing Job Assignments

The `jobIds` field allows you to manage which jobs a candidate is associated with:

```javascript theme={null}
// Assign candidate to multiple jobs
await updateCandidate("candidate-uuid", {
  jobIds: ["job-1-uuid", "job-2-uuid", "job-3-uuid"],
});

// Add a new job to existing assignments
// Note: Fetch current state since PATCH replaces the entire jobIds array
const candidate = await getCandidate("candidate-uuid");
await updateCandidate("candidate-uuid", {
  jobIds: [...candidate.jobIds, "new-job-uuid"],
});

// Replace all job assignments
await updateCandidate("candidate-uuid", {
  jobIds: ["only-this-job-uuid"],
});

// Remove from all jobs (candidate pool)
await updateCandidate("candidate-uuid", {
  jobIds: [],
});
```

<Info>
  **Job Validation**: All job IDs in the `jobIds` array must reference existing
  jobs that belong to your API key's company. Invalid job IDs will result in a
  validation error.
</Info>

## Status Workflow

Candidates progress through statuses:

* `APPLIED` → `IN_PROCESS` → `INTERVIEWED` → `HIRED`
* Or: `APPLIED` → `REJECTED` / `WITHDRAWN`

<Info>
  Status updates help track candidates through your recruitment pipeline. Update
  status as candidates progress to maintain accurate pipeline visibility.
</Info>

## Company Isolation

You can only update candidates that belong to your API key's company. The API validates company ownership before allowing updates, ensuring complete data isolation between companies.

## Error Scenarios

* **404 Not Found**: Candidate doesn't exist or has been deleted
* **403 Forbidden**: Candidate belongs to a different company, or job IDs reference jobs from other companies
* **400 Bad Request**: Invalid field values, validation errors, or non-existent job IDs

## Related Resources

<CardGroup cols={2}>
  <Card title="Candidates Resource Guide" icon="user" href="/guides/resources/candidates">
    Learn about candidate management and status workflows
  </Card>

  <Card title="Get Candidate" icon="eye" href="/api-reference/candidates/get-candidate">
    Retrieve current candidate information
  </Card>

  <Card title="Create Candidate" icon="plus" href="/api-reference/candidates/create-candidate">
    Create new candidates
  </Card>
</CardGroup>


## OpenAPI

````yaml PATCH /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}:
    patch:
      tags:
        - Candidates
      summary: Update candidate
      description: >-
        Updates a candidate that belongs to the API key's company. Only basic
        profile/contact/status fields are supported.
      operationId: PublicCandidatesController_updateCandidate_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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicUpdateCandidateDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicCandidateDto'
      security:
        - bearer: []
components:
  schemas:
    PublicUpdateCandidateDto:
      type: object
      properties:
        firstName:
          type: string
          description: Candidate's first name
          example: John
          minLength: 1
          maxLength: 100
        lastName:
          type: string
          description: Candidate's last name
          example: Doe
          minLength: 1
          maxLength: 100
        email:
          type: string
          description: Candidate's email address
          example: john.doe@example.com
        phoneNumber:
          type: string
          description: Candidate's phone number in E.164 format
          example: '+421901234567'
          pattern: ^\+[1-9]\d{1,14}$
        gdprExpiryDate:
          type: string
          description: GDPR expiry date in ISO 8601 format (must be in the future)
          example: '2026-11-16'
          format: date
        status:
          type: string
          description: Candidate status
          enum:
            - UNDEFINED
            - APPLIED
            - IN_PROCESS
            - REJECTED
            - ACCEPTED
          example: IN_PROCESS
        jobIds:
          description: >-
            Array of job IDs to assign the candidate to (replaces existing
            assignments)
          example:
            - 123e4567-e89b-12d3-a456-426614174000
            - 987e6543-e21b-12d3-a456-426614174001
          type: array
          items:
            type: string
            format: uuid
        metadata:
          type: object
          description: >-
            Custom metadata (replaces existing metadata, max 10KB, 5 levels
            deep, 50 keys)
          example:
            source: LinkedIn
            referredBy: John Smith
        gender:
          type: string
          description: >-
            Candidate's gender. Set to 'male' or 'female' to override
            auto-detection, or null to clear and revert to auto-detection.
          enum:
            - male
            - female
          nullable: true
          example: female
        cvText:
          type: string
          description: >-
            The candidate's CV in plain text. This will be automatically
            anonymized.
          example: |-
            Jane Doe
            Software Engineer
            Experience: ...
          maxLength: 50000
        workHistory:
          type: array
          description: >-
            Optional work history items of the candidate (replaces existing
            assignments).
          maxItems: 20
          items:
            $ref: '#/components/schemas/PublicCandidateWorkHistoryItemDto'
    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

````