Skip to main content
PATCH
/
candidates
/
{id}
Update candidate
curl --request PATCH \
  --url https://api.instaview.sk/candidates/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phoneNumber": "+421901234567",
  "gdprExpiryDate": "2026-11-16",
  "status": "IN_PROCESS",
  "jobIds": [
    "123e4567-e89b-12d3-a456-426614174000",
    "987e6543-e21b-12d3-a456-426614174001"
  ],
  "metadata": {
    "source": "LinkedIn",
    "referredBy": "John Smith"
  },
  "gender": "female",
  "cvText": "Jane Doe\nSoftware Engineer\nExperience: ..."
}
'
{
  "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: ..."
}
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: 
// 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
}

​
Managing Job Assignments

The jobIds field allows you to manage which jobs a candidate is associated with: 
// 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: [],
});
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.

​
Status Workflow

Candidates progress through statuses:
  • APPLIED → IN_PROCESS → INTERVIEWED → HIRED
  • Or: APPLIED → REJECTED / WITHDRAWN
Status updates help track candidates through your recruitment pipeline. Update status as candidates progress to maintain accurate pipeline visibility.

​
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

Candidates Resource Guide

Learn about candidate management and status workflows

Get Candidate

Retrieve current candidate information

Create Candidate

Create new candidates

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Path Parameters

​
id
string<uuid>
required

Query Parameters

​
companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Body

application/json
​
firstName
string

Candidate's first name

Required string length: 1 - 100
Example:

"John"

​
lastName
string

Candidate's last name

Required string length: 1 - 100
Example:

"Doe"

​
email
string

Candidate's email address

Example:

"john.doe@example.com"

​
phoneNumber
string

Candidate's phone number in E.164 format

Pattern: ^\+[1-9]\d{1,14}$
Example:

"+421901234567"

​
gdprExpiryDate
string<date>

GDPR expiry date in ISO 8601 format (must be in the future)

Example:

"2026-11-16"

​
status
enum<string>

Candidate status

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

"IN_PROCESS"

​
jobIds
string<uuid>[]

Array of job IDs to assign the candidate to (replaces existing assignments)

Example:
[
  "123e4567-e89b-12d3-a456-426614174000",
  "987e6543-e21b-12d3-a456-426614174001"
]
​
metadata
object

Custom metadata (replaces existing metadata, max 10KB, 5 levels deep, 50 keys)

Example:
{
  "source": "LinkedIn",
  "referredBy": "John Smith"
}
​
gender
enum<string> | null

Candidate's gender. Set to 'male' or 'female' to override auto-detection, or null to clear and revert to auto-detection.

Available options:
male,
female
Example:

"female"

​
cvText
string

The candidate's CV in plain text. This will be automatically anonymized.

Maximum string length: 50000
Example:

"Jane Doe\nSoftware Engineer\nExperience: ..."

Response

200 - application/json
​
id
string
required

Candidate ID

Example:

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

​
firstName
string
required

Candidate's first name

Example:

"John"

​
lastName
string
required

Candidate's last name

Example:

"Doe"

​
status
enum<string>
required

Candidate status

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

"APPLIED"

​
createdAt
string<date-time>
required

Created timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

​
updatedAt
string<date-time>
required

Updated timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

​
jobId
string
deprecated

[Deprecated] Single job ID; use jobIds instead.

Example:

"987e6543-e21b-12d3-a456-426614174000"

​
jobIds
string<uuid>[]

Jobs the candidate is assigned to.

Maximum array length: 50
​
email
string

Candidate's email address

Example:

"john.doe@example.com"

​
phoneNumber
string

Candidate's phone number

Example:

"+421915123456"

​
gdprExpiryDate
string<date>

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"

​
overallRating
number

Overall rating/match score (0-100)

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

85

​
metadata
object

Custom metadata

Example:
{
  "source": "LinkedIn",
  "externalId": "CAND-12345"
}
​
analysisCount
number

Number of analyses for this candidate (for quick overview)

Example:

2

​
interviewCount
number

Number of interviews for this candidate (for quick overview)

Example:

3

​
links
object

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
enum<string> | null

Candidate's gender. Used for gender-aware addressing in interviews. Null if not explicitly set (auto-detected from name).

Available options:
male,
female
Example:

"female"

​
anonymizedCvText
string

The candidate's anonymized CV in plain text.

Example:

"[NAME]\nSoftware Engineer\nExperience: ..."