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

# Candidates

> Browse, search, view, and add candidates in the ATS with grid or list views, profile details, applications, background checks, and documents.

Candidates is available at route `/hr/ats/candidates`. Access follows your organization's role and module configuration.

## Overview

The Candidates list page shows all candidates in the system with a total count. A search field filters by name or email. View mode can be toggled between grid (3-column card grid) and list (stacked cards). Candidates are rendered as `CandidateProfileCard` components. Pagination handles result sets over 20, displaying up to 5 page links. Clicking a card navigates to `/hr/ats/candidates/:id`. The page is also accessible as the **Candidates** tab within the ATS hub at `/hr/ats/dashboard`.

## Who it's for

Access follows your organization's role and module configuration.

## Before you start

* No preconditions; empty state is shown if no candidates have applied.

## Steps

<Steps>
  <Step title="Open Candidates">Navigate to `/hr/ats/candidates`.</Step>
  <Step title="Search">Enter a name or email in the search field.</Step>
  <Step title="Toggle view">Click the grid or list icon to switch display mode.</Step>
  <Step title="Open a candidate">Click a candidate card to navigate to the detail page.</Step>
</Steps>

## Key concepts

| Term                   | Meaning in code                                                  |
| ---------------------- | ---------------------------------------------------------------- |
| `CandidateFilters`     | Filter shape: `search` field applied to name/email               |
| `CandidateProfileCard` | Card component rendering candidate summary for grid/list display |

## Viewing a candidate

The Candidate Details page is available at route `/hr/ats/candidates/:id`. It displays a two-column layout. The left sidebar shows the candidate's avatar (initials), full name, email (linked), phone, LinkedIn URL (if present), a `CandidateTags` editable tag component, and a `CandidateNotes` section. A "Hired" badge appears if the candidate has a linked employee record. The right main area has three tabs: **Applications** (list of `ApplicationCard` components for each application the candidate has submitted), **Background Checks** (`BackgroundCheckSection`), and **Documents** (resume URL link if present, otherwise empty state). The candidate number is displayed as a monospace badge.

Before you start: a candidate record must exist; navigate from `/hr/ats/candidates`.

1. Navigate to `/hr/ats/candidates` and click a candidate card to open the detail page.
2. Check name, contact info, tags, and notes in the left sidebar.
3. Click the Applications tab to see all applications submitted by this candidate.
4. Click the Background Checks tab to review or initiate background check status.
5. Click the Documents tab; if a resume URL is stored, click **View Resume** to open it.

**Key detail concepts:**

| Term                     | Meaning in code                                                                     |
| ------------------------ | ----------------------------------------------------------------------------------- |
| `candidate_number`       | System-assigned candidate identifier displayed as monospace badge                   |
| `employee_id`            | If present, indicates the candidate has been hired and linked to an employee record |
| `CandidateTags`          | Editable tag component for categorizing the candidate                               |
| `BackgroundCheckSection` | Component for background check management                                           |

## Creating a candidate

`/hr/ats/candidates/new` is listed in the platform navigation label registry but has no corresponding `<Route>` in the HR router. Adding a new candidate to the ATS may be handled via an action on the Candidate List page (`CandidateListPage` at `/hr/ats/candidates`). Direct navigation to this path may result in a 404.

Before you start: visit `/hr/ats/candidates` to access the candidate list and any available candidate creation controls.

1. Navigate to `/hr/ats/candidates`.
2. Use the available action to add a new candidate.

## Related

<Columns cols={2}>
  <Card title="Human Resources" icon="users" href="/hr/overview">
    Human Resources core overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index">
    Documentation coverage and governance.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/hr.tsx
  * src/cores/hr/pages/ats/CandidateListPage.tsx
  * src/cores/hr/pages/ats/CandidateDetailPage.tsx
  * src/cores/hr/hooks/ats/useCandidates.ts
  * src/cores/hr/hooks/ats/useCandidateDetail.ts
  * src/platform/navigation/route-labels.ts
</Accordion>