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

# Manage Hiring Pipeline

> Move candidates through hiring stages, send automated communications, and run bulk status updates in Essal Careers.

The **hiring pipeline** in Essal Careers is a configurable sequence of stages that candidates move through from application to offer. This guide covers stage configuration, moving candidates, and automating communications.

## Pipeline Stages

Careers pipelines are separate from Sales pipelines and are defined per job or inherited from a default template. A typical pipeline looks like:

```json theme={null}
{
  "id": "cpl_01HXYZ1111",
  "name": "Default Engineering Pipeline",
  "stages": [
    { "id": "stg_01HXYZS1", "name": "Application Review", "order": 1 },
    { "id": "stg_01HXYZS2", "name": "Phone Screen", "order": 2 },
    { "id": "stg_01HXYZS3", "name": "Technical Interview", "order": 3 },
    { "id": "stg_01HXYZS4", "name": "Final Round", "order": 4 },
    { "id": "stg_01HXYZS5", "name": "Offer", "order": 5 }
  ]
}
```

## Moving a Candidate

```bash theme={null}
PATCH /v1/careers/applications/app_01HXYZAPP1
{
  "stage_id": "stg_01HXYZS3",
  "stage_note": "Passed phone screen. Scheduling technical interview."
}
```

A `careers.application.stage_changed` event fires on every transition.

## Automated Email Templates

Configure stage-transition emails to keep candidates informed automatically:

```bash theme={null}
POST /v1/careers/pipelines/cpl_01HXYZ1111/automations
{
  "trigger": "stage_entered",
  "stage_id": "stg_01HXYZS2",
  "action": "send_email",
  "template": "phone_screen_invite",
  "sender": "recruiting@example.com"
}
```

Available built-in templates: `application_received`, `phone_screen_invite`, `interview_invite`, `rejection_standard`, `offer_letter`.

## Bulk Status Updates

Move multiple candidates at once using bulk operations:

```bash theme={null}
POST /v1/careers/applications/bulk-update
{
  "application_ids": ["app_01HXYZAPP1", "app_01HXYZAPP2", "app_01HXYZAPP3"],
  "action": "advance_stage"
}
```

Or disqualify multiple candidates with a single call:

```bash theme={null}
POST /v1/careers/applications/bulk-disqualify
{
  "application_ids": ["app_01HXYZAPP4", "app_01HXYZAPP5"],
  "reason": "position_filled",
  "notify_candidates": true
}
```

<Warning>
  Bulk operations are processed asynchronously. Check the returned `batch_id` to monitor progress and review any per-application errors.
</Warning>

## Hiring Metrics

Track pipeline health with the metrics endpoint:

```bash theme={null}
GET /v1/careers/jobs/job_01HXYZJOB1/metrics
```

Returns: total applicants, conversion rates between stages, average time in each stage, and time-to-hire statistics.