> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hirempire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a job's candidates

> Retrieve all candidates for a specific job from your Hirempire workspace

## Query Parameters

<ParamField query="job_id" type="string" required placeholder="Enter job ID">
  The unique identifier of the job to retrieve candidates for
</ParamField>

## Authentication

<ResponseField name="Authorization" type="string" required>
  Bearer authentication header of the form `Bearer <token>`, where `<token>` is your API token.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.hirempire.com/v1/job-candidates?job_id={job_id}' \
  --header 'Authorization: Bearer sk-••••••••••••'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.hirempire.com/v1/job-candidates?job_id={job_id}', {
    method: 'GET',
    headers: { 'Authorization': 'Bearer sk-••••••••••••' }
  });
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.hirempire.com/v1/job-candidates"
  headers = { "Authorization": "Bearer sk-••••••••••••" }
  params = { "job_id": "{job_id}" }

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.hirempire.com/v1/job-candidates?job_id={job_id}',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => array(
      'Authorization: Bearer sk-••••••••••••'
    ),
  ));

  $response = curl_exec($curl);
  curl_close($curl);

  print_r(json_decode($response, true));
  ?>
  ```
</RequestExample>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="total_candidates" type="integer">
  Total number of candidates for the given job
</ResponseField>

<ResponseField name="candidates" type="array">
  Array of candidate objects

  <Expandable title="Candidate object properties">
    <ResponseField name="id" type="string">
      Unique identifier for the candidate
    </ResponseField>

    <ResponseField name="applied_at" type="string">
      ISO 8601 timestamp when the candidate applied
    </ResponseField>

    <ResponseField name="type" type="string">
      Candidate sub-type. One of: `applicant` `prospect` `upload`
    </ResponseField>

    <ResponseField name="name" type="string">
      Full name
    </ResponseField>

    <ResponseField name="email" type="string">
      Email address
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      Phone number
    </ResponseField>

    <ResponseField name="linkedin_url" type="string">
      LinkedIn profile URL
    </ResponseField>

    <ResponseField name="cv_url" type="string">
      URL to the candidate's CV/resume
    </ResponseField>

    <ResponseField name="photo_url" type="string">
      URL to the candidate's photo
    </ResponseField>

    <ResponseField name="source" type="string">
      Source where the candidate came from
    </ResponseField>

    <ResponseField name="status" type="string">
      Current pipeline status. One of: `applied` `screening` `phone_screen` `interview` `technical` `offer` `hired` `rejected` `withdrawn` `on_hold` `shortlisted` `qualified` `uploaded`
    </ResponseField>

    <ResponseField name="nationality" type="string">
      Candidate nationality
    </ResponseField>

    <ResponseField name="location" type="string">
      Candidate location (city)
    </ResponseField>

    <ResponseField name="experience_years" type="number">
      Years of professional experience
    </ResponseField>

    <ResponseField name="salary_expectation" type="number">
      Salary expectation in the workspace's default currency
    </ResponseField>

    <ResponseField name="job_id" type="string">
      ID of the job the candidate applied to
    </ResponseField>

    <ResponseField name="job_title" type="string">
      Title of the job the candidate applied to
    </ResponseField>

    <ResponseField name="ai_summary" type="string">
      AI-generated summary of the candidate
    </ResponseField>

    <ResponseField name="ai_score" type="number">
      AI score from 0–100
    </ResponseField>

    <ResponseField name="ai_decision" type="string">
      AI hiring recommendation
    </ResponseField>

    <ResponseField name="ai_match_percentage" type="number">
      Job-to-candidate match percentage
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "total_candidates": 1,
    "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
      }
    ]
  }
  ```
</ResponseExample>

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "success": false,
  "error": "Query parameter 'job_id' is required."
}
```

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "error": "Invalid token"
}
```

### 404 Not Found

```json theme={null}
{
  "success": false,
  "error": "Job not found"
}
```