curl --location --request GET 'https://api.hirempire.com/v1/get-candidate?candidate_id={candidate_id}' \
--header 'Authorization: Bearer sk-••••••••••••'
const response = await fetch('https://api.hirempire.com/v1/get-candidate?candidate_id={candidate_id}', {
method: 'GET',
headers: { 'Authorization': 'Bearer sk-••••••••••••' }
});
const data = await response.json();
console.log(data);
import requests
url = "https://api.hirempire.com/v1/get-candidate"
headers = { "Authorization": "Bearer sk-••••••••••••" }
params = { "candidate_id": "{candidate_id}" }
response = requests.get(url, headers=headers, params=params)
print(response.json())
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.hirempire.com/v1/get-candidate?candidate_id={candidate_id}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer sk-••••••••••••'
),
));
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));
?>
{
"success": true,
"candidate": {
"id": "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
"applied_at": "2026-06-18T12:30:00.000Z",
"type": "applicant",
"name": "John Doe",
"email": "john.doe@example.com",
"phone_number": "+15551234567",
"linkedin_url": "https://www.linkedin.com/in/johndoe",
"cv_url": "https://example.com/cv/johndoe.pdf",
"photo_url": "https://example.com/photos/johndoe.jpg",
"source": "LinkedIn",
"status": "shortlisted",
"nationality": "United States",
"location": "San Francisco",
"experience_years": 6,
"salary_expectation": 120000,
"job_id": "f3a2c1d4-1111-4222-9333-444455556666",
"job_title": "Senior Software Engineer",
"ai_summary": "Strong full-stack background, 6 yrs React + Node.",
"ai_score": 85,
"ai_decision": "Shortlist",
"ai_match_percentage": 92
}
}
Candidates
Get a specific candidate
Retrieve a single candidate by candidate ID from your Hirempire workspace
GET
/
v1
/
get-candidate
curl --location --request GET 'https://api.hirempire.com/v1/get-candidate?candidate_id={candidate_id}' \
--header 'Authorization: Bearer sk-••••••••••••'
const response = await fetch('https://api.hirempire.com/v1/get-candidate?candidate_id={candidate_id}', {
method: 'GET',
headers: { 'Authorization': 'Bearer sk-••••••••••••' }
});
const data = await response.json();
console.log(data);
import requests
url = "https://api.hirempire.com/v1/get-candidate"
headers = { "Authorization": "Bearer sk-••••••••••••" }
params = { "candidate_id": "{candidate_id}" }
response = requests.get(url, headers=headers, params=params)
print(response.json())
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.hirempire.com/v1/get-candidate?candidate_id={candidate_id}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer sk-••••••••••••'
),
));
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));
?>
{
"success": true,
"candidate": {
"id": "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
"applied_at": "2026-06-18T12:30:00.000Z",
"type": "applicant",
"name": "John Doe",
"email": "john.doe@example.com",
"phone_number": "+15551234567",
"linkedin_url": "https://www.linkedin.com/in/johndoe",
"cv_url": "https://example.com/cv/johndoe.pdf",
"photo_url": "https://example.com/photos/johndoe.jpg",
"source": "LinkedIn",
"status": "shortlisted",
"nationality": "United States",
"location": "San Francisco",
"experience_years": 6,
"salary_expectation": 120000,
"job_id": "f3a2c1d4-1111-4222-9333-444455556666",
"job_title": "Senior Software Engineer",
"ai_summary": "Strong full-stack background, 6 yrs React + Node.",
"ai_score": 85,
"ai_decision": "Shortlist",
"ai_match_percentage": 92
}
}
Query Parameters
string
required
The unique identifier of the candidate to retrieve
Authentication
string
required
Bearer authentication header of the form
Bearer <token>, where <token> is your API token.curl --location --request GET 'https://api.hirempire.com/v1/get-candidate?candidate_id={candidate_id}' \
--header 'Authorization: Bearer sk-••••••••••••'
const response = await fetch('https://api.hirempire.com/v1/get-candidate?candidate_id={candidate_id}', {
method: 'GET',
headers: { 'Authorization': 'Bearer sk-••••••••••••' }
});
const data = await response.json();
console.log(data);
import requests
url = "https://api.hirempire.com/v1/get-candidate"
headers = { "Authorization": "Bearer sk-••••••••••••" }
params = { "candidate_id": "{candidate_id}" }
response = requests.get(url, headers=headers, params=params)
print(response.json())
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.hirempire.com/v1/get-candidate?candidate_id={candidate_id}',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer sk-••••••••••••'
),
));
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));
?>
Response
boolean
Indicates if the request was successful
object
The candidate object
Show Candidate object properties
Show Candidate object properties
string
Unique identifier for the candidate
string
ISO 8601 timestamp when the candidate entered the workspace
string
Candidate sub-type. One of:
applicant (applied to a job), prospect (sourced), upload (manually uploaded)string
Full name of the candidate
string
Email address
string
Phone number
string
LinkedIn profile URL
string
URL to the candidate’s CV/resume
string
URL to the candidate’s photo
string
Source where the candidate came from
string
Current pipeline status. One of:
applied screening phone_screen interview technical offer hired rejected withdrawn on_hold shortlisted qualified uploadedstring
Candidate nationality
string
Candidate location (city)
number
Years of professional experience
number
Salary expectation in the workspace’s default currency
string
ID of the job the candidate is associated with
string
Title of the associated job
string
AI-generated summary of the candidate
number
AI score from 0–100
string
AI hiring recommendation
number
Job-to-candidate match percentage
{
"success": true,
"candidate": {
"id": "8fc4ea3c-ecc4-4a92-96fd-a14436a79a1b",
"applied_at": "2026-06-18T12:30:00.000Z",
"type": "applicant",
"name": "John Doe",
"email": "john.doe@example.com",
"phone_number": "+15551234567",
"linkedin_url": "https://www.linkedin.com/in/johndoe",
"cv_url": "https://example.com/cv/johndoe.pdf",
"photo_url": "https://example.com/photos/johndoe.jpg",
"source": "LinkedIn",
"status": "shortlisted",
"nationality": "United States",
"location": "San Francisco",
"experience_years": 6,
"salary_expectation": 120000,
"job_id": "f3a2c1d4-1111-4222-9333-444455556666",
"job_title": "Senior Software Engineer",
"ai_summary": "Strong full-stack background, 6 yrs React + Node.",
"ai_score": 85,
"ai_decision": "Shortlist",
"ai_match_percentage": 92
}
}
Error Responses
400 Bad Request
{
"success": false,
"error": "Query parameter 'candidate_id' is required."
}
{
"success": false,
"error": "Only 'candidate_id' query parameter is allowed."
}
401 Unauthorized
{
"success": false,
"error": "Invalid token"
}
404 Not Found
{
"success": false,
"error": "Candidate not found"
}
Was this page helpful?
⌘I