Skip to main content
GET
/
candidates
/
{id}
Get candidate by ID
curl --request GET \
  --url https://api.instaview.sk/candidates/{id} \
  --header 'Authorization: Bearer <token>'
{
  "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: ..."
}
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

Candidates Resource Guide

Learn about candidate structure and status workflows

Update Candidate

Modify candidate information

List Candidates

Browse all 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.

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: ..."