> ## 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 specific candidate

> Retrieve a single candidate by candidate ID from your Hirempire workspace

## Query Parameters

<ParamField query="candidate_id" type="string" required placeholder="Enter candidate ID">
  The unique identifier of the candidate to retrieve
</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/get-candidate?candidate_id={candidate_id}' \
  --header 'Authorization: Bearer sk-••••••••••••'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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));
  ?>
  ```
</RequestExample>

## Response

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

<ResponseField name="candidate" type="object">
  The candidate object

  <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 entered the workspace
    </ResponseField>

    <ResponseField name="type" type="string">
      Candidate sub-type. One of: `applicant` (applied to a job), `prospect` (sourced), `upload` (manually uploaded)
    </ResponseField>

    <ResponseField name="name" type="string">
      Full name of the candidate
    </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 is associated with
    </ResponseField>

    <ResponseField name="job_title" type="string">
      Title of the associated job
    </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,
    "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
    }
  }
  ```
</ResponseExample>

## Error Responses

### 400 Bad Request

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

```json theme={null}
{
  "success": false,
  "error": "Only 'candidate_id' query parameter is allowed."
}
```

### 401 Unauthorized

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

### 404 Not Found

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