Update Candidate

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": "[email protected]",
  "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"
  }
}
'

{
  "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": "[email protected]",
  "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"
  }
}

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": "[email protected]",
  "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"
  }
}
'

{
  "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": "[email protected]",
  "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"
  }
}

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
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": "[email protected]",
  "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": []
}

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

string<uuid>

required

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"

string

Candidate's email address

Example:

"[email protected]"

phoneNumber

string

Candidate's phone number in E.164 format

Example:

"+421901234567"

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"
}

Response

200 - application/json

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

string

Candidate's email address

Example:

"[email protected]"

phoneNumber

string

Candidate's phone number

Example:

"+421915123456"

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"
}

Get Candidate Delete Candidate

⌘I

Overview

Agents

Jobs

Candidates

Companies

Interviews

Billing

Webhooks

Overview

Use Cases

Partial Updates

Managing Job Assignments

Status Workflow

Company Isolation

Error Scenarios

Candidates Resource Guide

Get Candidate

Create Candidate

Authorizations

Path Parameters

Body

Response

Overview

Agents

Jobs

Candidates

Companies

Interviews

Billing

Webhooks

​Overview

​Use Cases

​Partial Updates

​Managing Job Assignments

​Status Workflow

​Company Isolation

​Error Scenarios

​Related Resources

Candidates Resource Guide

Get Candidate

Create Candidate

Authorizations

Path Parameters

Body

Response

Overview

Use Cases

Partial Updates

Managing Job Assignments

Status Workflow

Company Isolation

Error Scenarios

Related Resources