Get all candidates - Hirempire Docs

curl --location --request GET 'https://api.hirempire.com/v1/candidates' \
--header 'Authorization: Bearer sk-••••••••••••'

{
  "success": true,
  "total_candidates": 2,
  "candidates": [
    {
      "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
    },
    {
      "id": "0c8b5e54-e053-40b2-8c9c-b45ec90acf8a",
      "applied_at": "2026-06-17T09:15:00.000Z",
      "type": "prospect",
      "name": "Sarah Smith",
      "email": "sarah.smith@example.com",
      "phone_number": "+447987654321",
      "linkedin_url": "https://www.linkedin.com/in/sarahsmith",
      "cv_url": null,
      "photo_url": null,
      "source": "Sourcing",
      "status": "qualified",
      "nationality": "United Kingdom",
      "location": "London",
      "experience_years": 8,
      "salary_expectation": null,
      "job_id": null,
      "job_title": null,
      "ai_summary": null,
      "ai_score": null,
      "ai_decision": null,
      "ai_match_percentage": null
    }
  ]
}

GET

candidates

curl --location --request GET 'https://api.hirempire.com/v1/candidates' \
--header 'Authorization: Bearer sk-••••••••••••'

{
  "success": true,
  "total_candidates": 2,
  "candidates": [
    {
      "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
    },
    {
      "id": "0c8b5e54-e053-40b2-8c9c-b45ec90acf8a",
      "applied_at": "2026-06-17T09:15:00.000Z",
      "type": "prospect",
      "name": "Sarah Smith",
      "email": "sarah.smith@example.com",
      "phone_number": "+447987654321",
      "linkedin_url": "https://www.linkedin.com/in/sarahsmith",
      "cv_url": null,
      "photo_url": null,
      "source": "Sourcing",
      "status": "qualified",
      "nationality": "United Kingdom",
      "location": "London",
      "experience_years": 8,
      "salary_expectation": null,
      "job_id": null,
      "job_title": null,
      "ai_summary": null,
      "ai_score": null,
      "ai_decision": null,
      "ai_match_percentage": null
    }
  ]
}

Query Parameters

type

string

Filter the result by candidate type. One of: applicant prospect upload. If omitted, all three types are returned.

Authentication

Authorization

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/candidates' \
--header 'Authorization: Bearer sk-••••••••••••'

Response

success

boolean

Indicates if the request was successful

total_candidates

integer

Total number of candidates returned

candidates

array

Array of candidate objects

Show Candidate object properties

string

Unique identifier for the candidate

applied_at

string

ISO 8601 timestamp when the candidate entered the workspace

type

string

Candidate sub-type. One of: applicant (applied to a job), prospect (sourced), upload (manually uploaded)

name

string

Full name of the candidate

string

Email address

phone_number

string

Phone number

linkedin_url

string

LinkedIn profile URL

cv_url

string

URL to the candidate’s CV/resume

photo_url

string

URL to the candidate’s photo

source

string

Source where the candidate came from (e.g. LinkedIn, Referral, Indeed)

status

string

Current pipeline status. One of: applied screening phone_screen interview technical offer hired rejected withdrawn on_hold shortlisted qualified uploaded

nationality

string

Candidate nationality

location

string

Candidate location (city)

experience_years

number

Years of professional experience

salary_expectation

number

Salary expectation in the workspace’s default currency

job_id

string

ID of the job the candidate is associated with (null for unassigned)

job_title

string

Title of the associated job (null for unassigned)

ai_summary

string

AI-generated summary of the candidate

ai_score

number

AI score from 0–100

ai_decision

string

AI hiring recommendation (e.g. Shortlist, Review, Reject)

ai_match_percentage

number

Job-to-candidate match percentage

{
  "success": true,
  "total_candidates": 2,
  "candidates": [
    {
      "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
    },
    {
      "id": "0c8b5e54-e053-40b2-8c9c-b45ec90acf8a",
      "applied_at": "2026-06-17T09:15:00.000Z",
      "type": "prospect",
      "name": "Sarah Smith",
      "email": "sarah.smith@example.com",
      "phone_number": "+447987654321",
      "linkedin_url": "https://www.linkedin.com/in/sarahsmith",
      "cv_url": null,
      "photo_url": null,
      "source": "Sourcing",
      "status": "qualified",
      "nationality": "United Kingdom",
      "location": "London",
      "experience_years": 8,
      "salary_expectation": null,
      "job_id": null,
      "job_title": null,
      "ai_summary": null,
      "ai_score": null,
      "ai_decision": null,
      "ai_match_percentage": null
    }
  ]
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": "Only 'type' query parameter is allowed."
}

{
  "success": false,
  "error": "type must be one of: applicant, prospect, upload"
}

401 Unauthorized

{
  "success": false,
  "error": "Invalid token"
}

{
  "success": false,
  "error": "Token is expired"
}

Create job source Get a specific candidate

​Query Parameters

​Authentication

​Response

​Error Responses

​400 Bad Request

​401 Unauthorized

Query Parameters

Authentication

Response

Error Responses

400 Bad Request

401 Unauthorized